hiredis-py 技术文档

1. 安装指南

1.1 系统要求

• Python 3.8+：hiredis-py 需要 Python 3.8 或更高版本。
• Python 开发头文件：在安装 hiredis-py 时，确保系统中已安装 Python 开发头文件。在 Ubuntu/Debian 系统上，可以通过以下命令安装：

  sudo apt-get install python3-dev
  

1.2 安装步骤

hiredis-py 可以通过 PyPI 进行安装，使用以下命令即可：

pip install hiredis

1.3 手动构建与测试

如果你需要手动构建和测试 hiredis-py，可以按照以下步骤操作：

1. 克隆仓库并递归初始化子模块：

   git clone --recurse-submodules https://github.com/redis/hiredis-py
   

2. 编译并构建扩展：

   python setup.py build_ext --inplace
   

3. 运行测试：

   python -m pytest
   

2. 项目使用说明

2.1 基本使用

hiredis-py 提供了一个 Reader 类，用于解析从 Redis 连接中读取的数据流。Reader 类不处理 I/O，仅负责解析回复。

2.1.1 创建 Reader 实例

import hiredis

reader = hiredis.Reader()

2.1.2 解析回复

Reader 类有两个主要方法：

• feed(data)：将数据追加到内部缓冲区。
• gets()：从缓冲区中读取并返回一个完整的回复。

示例：

reader.feed("$5\r\nhello\r\n")
reply = reader.gets()
print(reply)  # 输出: b'hello'

2.2 处理 Unicode 数据

Reader 类支持将批量数据解码为任何 Python 支持的编码格式。可以通过在初始化 Reader 时指定 encoding 和 errors 参数来实现。

示例：

reader = hiredis.Reader(encoding="utf-8", errors="strict")
reader.feed(b"$3\r\n\xe2\x98\x83\r\n")
reply = reader.gets()
print(reply)  # 输出: '☃'

2.3 错误处理

• 协议错误：当发生协议错误时，会抛出 hiredis.ProtocolError 异常。
• Redis 错误回复：Redis 返回的错误回复（如 -ERR ...）会返回 hiredis.ReplyError 对象，但不会抛出异常。

3. 项目 API 使用文档

3.1 Reader 类

• __init__(self, encoding=None, errors='strict', notEnoughData=False, protocolError=ProtocolError, replyError=ReplyError)

  • encoding：指定解码批量数据的编码格式。
  • errors：指定解码错误处理方式，默认为 'strict'。
  • notEnoughData：当缓冲区中没有足够数据时返回的自定义对象。
  • protocolError：自定义协议错误类。
  • replyError：自定义 Redis 错误回复类。

• feed(self, data)

  • 将数据追加到内部缓冲区。

• gets(self)

  • 从缓冲区中读取并返回一个完整的回复。如果缓冲区中没有足够的数据，返回 False 或自定义的 notEnoughData 对象。

4. 项目安装方式

4.1 通过 PyPI 安装

pip install hiredis

4.2 手动构建与安装

1. 克隆仓库并递归初始化子模块：

   git clone --recurse-submodules https://github.com/redis/hiredis-py
   

2. 编译并构建扩展：

   python setup.py build_ext --inplace
   

3. 运行测试：

   python -m pytest
   

通过以上步骤，你可以成功安装并使用 hiredis-py 项目。