libvalkey

Warnings

• breaking The library was renamed from `hiredis-py` to `libvalkey-py` in version 3.0.0. All `hiredis` imports must be updated to `libvalkey`.
  Fix: Change `import hiredis` to `import libvalkey` and update any references to `hiredis.Reader` to `libvalkey.Reader`.
• gotcha Building `libvalkey` from source (e.g., if a pre-compiled wheel is not available for your environment) requires Python development headers (e.g., `python3-dev` on Debian/Ubuntu) and a C compiler like `gcc`.
  Fix: Ensure `python3-dev` and `gcc` (or equivalent build tools for your OS) are installed before attempting `pip install libvalkey` if pre-built wheels are not available. For example, `sudo apt-get install python3-dev gcc` on Debian/Ubuntu.
• gotcha For error handling, `libvalkey.ProtocolError` is raised for invalid protocol states. However, `libvalkey.ReplyError` (for server-side error replies like `-ERR`) is *returned* by `gets()` and not raised as an exception by default.
  Fix: Explicitly check the return value of `reader.gets()` for instances of `libvalkey.ReplyError` if you want to handle server-generated errors. For example: `reply = reader.gets(); if isinstance(reply, libvalkey.ReplyError): handle_error(reply)`.
• gotcha When `libvalkey.Reader` is initialized with an `encoding` (e.g., 'utf-8'), bulk string replies are decoded. If the decoding fails and the `errors` parameter is set to 'strict' (the default), a `UnicodeDecodeError` will be raised.
  Fix: To handle decoding errors gracefully, initialize the `Reader` with a different `errors` handler, such as 'ignore', 'replace', or 'backslashreplace' (e.g., `libvalkey.Reader(encoding='utf-8', errors='replace')`).
• breaking Version 4.0.0 included changes to the `Reader`'s behavior, with a subsequent patch (v4.0.0b1) to 'partly restore the previous behaviour'. Users upgrading to or through v4.0.0 should review the changelog carefully for potential subtle changes in parsing logic.
  Fix: Thoroughly test existing code relying on `Reader` behavior when upgrading to v4.0.0 or later to ensure parsing logic remains consistent with expectations. Refer to the GitHub releases for specific changes.

Install

• pip install libvalkey Install stable version

Imports

• Reader

  from libvalkey import Reader

  The library was renamed from `hiredis-py` to `libvalkey-py` in version 3.0.0. Direct imports of `hiredis` will fail in `libvalkey-py` versions 3.0.0 and above.

Quickstart

The quickstart demonstrates how to initialize the `Reader` class, feed raw Valkey protocol bytes, and retrieve parsed replies. It also shows how to handle cases where insufficient data is fed, using a custom sentinel value.

import libvalkey

# The Reader class is responsible for parsing replies from a stream of data.
# It does not handle I/O itself.
reader = libvalkey.Reader()

# Feed raw Valkey protocol bytes to the reader
reader.feed(b"$5\r\nhello\r\n")

# Retrieve the parsed reply
reply = reader.gets()
print(f"Parsed reply: {reply}")

# Example with a list reply
reader.feed(b"*2\r\n$5\r\nhello\r\n$5\r\nworld\r\n")
list_reply = reader.gets()
print(f"Parsed list reply: {list_reply}")

# Example with custom sentinel for 'not enough data'
reader_ellipsis = libvalkey.Reader(notEnoughData=Ellipsis)
reader_ellipsis.feed(b"*2\r\n$5\r\nhello\r\n")
partial_reply = reader_ellipsis.gets()
print(f"Partial reply (needs more data): {partial_reply}")
reader_ellipsis.feed(b"$5\r\nworld\r\n")
full_reply = reader_ellipsis.gets()
print(f"Full reply: {full_reply}")