`pure-protobuf` 技术文档

1. 安装指南

pure-protobuf 是一个用于处理 Protocol Buffers 的 Python 库，支持使用 dataclasses 和 pydantic 来定义消息结构。以下是安装 pure-protobuf 的步骤：

使用 pip 安装

你可以通过 pip 来安装 pure-protobuf：

pip install pure-protobuf

安装依赖

pure-protobuf 依赖于 typing_extensions 和 pydantic（如果你选择使用 pydantic 来定义消息结构）。这些依赖项会在安装 pure-protobuf 时自动安装。

2. 项目的使用说明

pure-protobuf 允许你使用 Python 的 dataclasses 或 pydantic 来定义 Protocol Buffers 消息。以下是两种使用方式的示例：

使用 dataclasses 定义消息

from dataclasses import dataclass
from io import BytesIO

from pure_protobuf.annotations import Field
from pure_protobuf.message import BaseMessage
from typing_extensions import Annotated


@dataclass
class SearchRequest(BaseMessage):
    query: Annotated[str, Field(1)] = ""
    page_number: Annotated[int, Field(2)] = 0
    result_per_page: Annotated[int, Field(3)] = 0


request = SearchRequest(query="hello", page_number=1, result_per_page=10)
buffer = bytes(request)
assert buffer == b"\x0A\x05hello\x10\x01\x18\x0A"
assert SearchRequest.read_from(BytesIO(buffer)) == request

使用 pydantic 定义消息

from io import BytesIO

from pure_protobuf.annotations import Field
from pure_protobuf.message import BaseMessage
from pydantic import BaseModel
from typing_extensions import Annotated


class SearchRequest(BaseMessage, BaseModel):
    query: Annotated[str, Field(1)] = ""
    page_number: Annotated[int, Field(2)] = 0
    result_per_page: Annotated[int, Field(3)] = 0


request = SearchRequest(query="hello", page_number=1, result_per_page=10)
buffer = bytes(request)
assert buffer == b"\x0A\x05hello\x10\x01\x18\x0A"
assert SearchRequest.read_from(BytesIO(buffer)) == request

3. 项目 API 使用文档

pure-protobuf 提供了以下主要 API：

BaseMessage

BaseMessage 是所有消息类的基类。你可以通过继承 BaseMessage 并使用 dataclasses 或 pydantic 来定义消息结构。

Field

Field 是一个注解类，用于指定字段的编号。你可以通过 Annotated 来使用 Field，例如：

query: Annotated[str, Field(1)] = ""

序列化与反序列化

你可以使用 bytes() 函数将消息序列化为字节流，并使用 read_from() 方法从字节流中反序列化消息：

buffer = bytes(request)  # 序列化
request = SearchRequest.read_from(BytesIO(buffer))  # 反序列化

4. 项目安装方式

pure-protobuf 可以通过 pip 安装，具体步骤如下：

pip install pure-protobuf

如果你需要使用 pydantic，请确保已安装 pydantic：

pip install pydantic

安装完成后，你可以通过导入 pure_protobuf 模块来使用该库。

from pure_protobuf.message import BaseMessage
from pure_protobuf.annotations import Field
from typing_extensions import Annotated

通过以上步骤，你可以轻松地使用 pure-protobuf 来处理 Protocol Buffers 消息。