OBStruct

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

✨ 亮点

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

📊 基准测试

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

操作	单次耗时	相对 Pack
Pack	216.8 ns	1.00x
Update From	318.2 ns	1.47x
Update	329.3 ns	1.52x
Unpack From	628.5 ns	2.90x
Unpack	679.0 ns	3.13x

📄 详细报告：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 类型：

类型	说明
`int` / `unsigned_int`	标准整型
`long` / `unsigned_long`	长整型
`short` / `unsigned_short`	短整型
`float` / `double`	浮点数
`char` / `string`	字符/字符串
`array`	数组（⚠️ 建议传入 `array` 模块对象，避免 Python 序列）
`bool`	布尔值

🧠 推荐使用方式

场景	推荐方法	理由
高频单次打包	`pack`	最快基准操作
高频单次解析（复用对象）	`update_from`	最快解析方法，复用 + 偏移
需要新建对象	`unpack_from`	比 `unpack` 快 7.4%
批量处理	`iter_update`	每元素仅 270 ns
复杂结构批量解析	`complex_iter_update`	比解包版本快 56.4%
极致性能	手动 `memoryview` + `struct.unpack_from`	完全控制，零拷贝

🗺️ 路线图

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

📄 许可证

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

🙏 致谢

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

obstruct-0.6.1.tar.gz (108.6 kB view details)

Uploaded Sep 6, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

obstruct-0.6.1-py3-none-any.whl (15.7 kB view details)

Uploaded Sep 6, 2026 Python 3

File details

Details for the file obstruct-0.6.1.tar.gz.

File metadata

Download URL: obstruct-0.6.1.tar.gz
Upload date: Sep 6, 2026
Size: 108.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for obstruct-0.6.1.tar.gz
Algorithm	Hash digest
SHA256	`07163bcab2aad2d6aa6e206b09d2b214e5b68616dff506da5a38bb4f46e97a25`
MD5	`20e4feec2bc8e1924687814d8bf9bff8`
BLAKE2b-256	`3d17451af4d7b1aa64aa198ce7f45a84efe2044e3b76d94af1274af2d9c30b55`

See more details on using hashes here.

File details

Details for the file obstruct-0.6.1-py3-none-any.whl.

File metadata

Download URL: obstruct-0.6.1-py3-none-any.whl
Upload date: Sep 6, 2026
Size: 15.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for obstruct-0.6.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`4005b4c389abe71863eb66191ae91f27c2520b4cb2f7960b875cadfd21fd04ab`
MD5	`1b5d3dd71b032010f4a595cca8685115`
BLAKE2b-256	`4ec3543fbc6758ad6e6f1cfd5cd5efeefad626c7b397b0721b89ab7e34a8c622`