Metadata-Version: 2.5
Name: obstruct
Version: 0.5.1
Author-email: LittleNightSong <LittleNightSongYO@outlook.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.12
Description-Content-Type: text/markdown

_来自已弃坑的 `Hydrogenlib`，重拾起当初的决心_


> [!TIP]
> 这个项目来自 [`HydrogenLib`](https://github.com/LittleNightSong/HydrogenLib)的 `Objective-Struct` 模块，是一个脱离大项目的版本
>
> 同时，`HydrogenLib`中的 `Objective-Struct` 不再会更新

> [!TIP]
> 作者的主要开发精力放在了另一些项目上，也许很长时间这个项目都不会再更新

# OBStruct

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

## 亮点

- 纯 Python
- 基于类型注解的字段声明方式
- 支持 `struct` 标准库中的所有格式，并额外支持 array 类型
- 基于 AOT 的加速
- 完整的操作支持（打包、解包、流式处理）

> [!WARNING]
> 使用 `array` 类型时，建议不要传入 list 类型或其它 Python 序列，
> 可能会带来极大的性能影响

## 基准测试

### 系统环境

- 12th Gen Intel® Core (TM) i7-12700H

在 12个字段，10000 次操作，8轮取平均值的条件下：

- 打包：269.639ns 一次操作
- 解包：582.185ns 一次操作

> 新的测试报告请参见 [BENCHMARK_TEST](BENCHMARK_TEST.md)

## 安装

```commandline
pip install obstruct
```

如果使用 `uv` 等包管理器，则按照工具的方法安装即可

## 用法

首先声明一个 `Struct` 类型，它是一个 `dataclass`，也是一个 `struct`

```python
import obstruct as obs
from dataclasses import dataclass


@dataclass()
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 = data.pack()
    print(packed_data)

    restored = MyStruct.unpack(packed_data)
    print(restored)

    print(data == restored)

```

> [!TIP]
> 建议 dataclass 装饰器中使用 `slots=True` 以加速属性访问和内存效率

在上述示例中，你可能发现 `data != restored`，这是浮点数的精度限制导致的。 因此，我们不建议使用浮点数类型，浮点数在二进制传输中也不常见。

## 计划

- 展平装饰器，目前的 API 较为繁琐，需要简化为唯一的 `Struct` 基类
- 继续优化性能
- 通过存根文件强制表明类型似乎变得不再有效了
- 支持 Tag 联合类型，对标 `msgspec`
