OBStruct

一个简单、纯粹、极速的二进制解析库

✨ 亮点

• 纯 Python，零依赖，开箱即用
• 基于类型注解 声明字段，简洁直观
• 支持 struct 标准库全部格式，额外支持 array 类型
• AOT 编译加速，高性能解析
• 完整的操作支持：打包、解包、流式处理、偏移读写

📊 基准测试

测试环境：12th Gen Intel® Core™ i7-12700H | 12 个基本类型字段 | 64,000 次操作/方法

📄 详细报告：BENCHMARK_TEST-v0.6.0.md

🚀 v0.6.0 更新亮点

✅ 性能大幅提升

• Pack 系列全面优化，尤其是 复杂结构体 和 数组字段
• Complex Pack 性能提升 67.4%
• Complex Iter Update（批量更新）性能提升 36.0%

⚠️ 已知回退

Unpack 系列存在不同程度的性能倒退（相较 v0.5.0）：

• Unpack：+12.8%
• Unpack From：+25.3%
• Complex Unpack From：+21.9%

如果你的场景以 Pack / Update 为主，升级将获得显著收益；若以 Unpack 为主，建议评估后升级。

📦 安装

pip install obstruct

使用 uv 或 poetry 等工具时按对应方式安装即可。

🧩 快速开始

声明一个 Struct 类型——它同时是一个 dataclass：

from dataclasses import dataclass

import obstruct as obs


@dataclass(slots=True)  # slots=True 提升性能
class MyStruct(obs.Struct):
    a: int
    b: float
    c: obs.long
    d: obs.unsigned_short


if __name__ == "__main__":
    data = MyStruct(a=0, b=2.0, c=10000, d=14545)

    # 打包
    packed = data.pack()
    print(packed)  # bytes

    # 解包
    restored = MyStruct.unpack(packed)
    print(restored)

    # 注意：浮点数精度可能导致 data != restored

📖 支持的类型

继承自 struct 标准库的所有格式，并扩展了 array 类型：

🧠 推荐使用方式

🗺️ 路线图

• 简化 API：移除繁琐装饰器，统一为 Struct 基类
• 持续性能优化：进一步缩小 Unpack 路径的性能差距
• 类型存根优化：重新评估类型提示的强制方式
• Tag 联合类型：对标 msgspec 的联合体支持

📄 许可证

项目使用 BSD 3-Clause 许可证，全文参见 LICENSE

🙏 致谢

本项目源自 HydrogenLib 的 Objective-Struct 模块，现已独立维护。