Hiredis Python Wrapper

Warnings

• breaking In `hiredis` v3.0.0, the parsing of Redis Sets was changed to return Python lists instead of Python sets. This was considered a bug fix but is a breaking change for applications expecting Python set objects.
  Fix: Update your code to expect Python lists when parsing Redis SET command replies. Convert to a set explicitly if needed: `set_data = set(parsed_list_from_hiredis)`.
• gotcha Installing `hiredis` from source (e.g., when a pre-built wheel is not available for your specific Python version or OS) requires Python development headers (e.g., `python3-dev` on Debian/Ubuntu) and a C compiler (like `gcc`) to be installed on your system. Without these, `pip install hiredis` might fail with compilation errors.
  Fix: Ensure you have the necessary build tools and Python development headers. For Debian/Ubuntu, `sudo apt-get install python3-dev gcc`. For other systems, consult your package manager documentation.
• gotcha When `hiredis.Reader` encounters a protocol error (e.g., due to a corrupted stream), it raises `hiredis.ProtocolError`. This indicates an unrecoverable state for the current reader instance, and the I/O code feeding data to the reader should typically reconnect or create a new reader.
  Fix: Implement robust error handling around `reader.gets()`. Catch `hiredis.ProtocolError` and re-establish your Redis connection and parser instance.
• gotcha If you are using `redis-py` version 5.x or later with an older `hiredis` version (e.g., < 3.0), `redis-py` might not correctly detect and utilize `hiredis` for parsing, leading to a `NameError: name 'hiredis' is not defined` if `redis-py` attempts to use `hiredis.pack_command` conditionally. `redis-py` version 5.x explicitly checks for `hiredis.__version__ >= 3`.
  Fix: Ensure your `hiredis` installation is version 3.0.0 or higher when using `redis-py` versions 5.x or later. Upgrade `hiredis` by running `pip install --upgrade hiredis`.
• gotcha The `hiredis.Reader.gets()` method returns `False` when the internal buffer does not contain a full, complete reply. It does not raise an error or return `None` or an empty string. This behavior needs to be explicitly checked when interacting with the reader.
  Fix: Always check the return value of `reader.gets()` for `False` to determine if more data is needed before a complete reply can be parsed. Example: `reply = reader.gets(); if reply is False: ...`.

Install

• pip install hiredis Basic Installation
• pip install "redis[hiredis]" With redis-py (recommended for performance)

Imports

• Reader

  from hiredis import Reader

  The primary class for parsing Redis protocol streams.

Quickstart

This quickstart demonstrates the direct usage of `hiredis.Reader` to parse Redis protocol strings. The `feed()` method takes raw bytes, and `gets()` retrieves the next complete parsed reply. It handles different Redis data types and returns `False` if a complete reply is not yet available in the buffer.

import hiredis

# Create a Reader instance to parse Redis protocol data
reader = hiredis.Reader()

# Example 1: Parse a simple string reply ('+OK\r\n')
reader.feed(b"+OK\r\n")
result_ok = reader.gets()
print(f"Parsed simple string: {result_ok}")

# Example 2: Parse a bulk string reply ('$5\r\nhello\r\n')
reader.feed(b"$5\r\nhello\r\n")
result_hello = reader.gets()
print(f"Parsed bulk string: {result_hello}")

# Example 3: Parse an array reply ('*2\r\n$5\r\nhello\r\n$5\r\nworld\r\n')
reader.feed(b"*2\r\n$5\r\nhello\r\n$5\r\nworld\r\n")
result_array = reader.gets()
print(f"Parsed array: {result_array}")

# Example 4: Handle incomplete data - gets() returns False if no full reply is available
reader.feed(b"$6\r\nfoobar")
incomplete_result = reader.gets()
print(f"Incomplete data (should be False): {incomplete_result}")
reader.feed(b"\r\n") # Complete the data
completed_result = reader.gets()
print(f"Completed data: {completed_result}")