Metadata-Version: 2.5
Name: obstruct
Version: 0.6.0
Author-email: LittleNightSong <LittleNightSongYO@outlook.com>
License-File: LICENSE
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
Requires-Dist: typing
Description-Content-Type: text/markdown

# 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](./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** 为主，建议评估后升级。

---

## 📦 安装

```bash
pip install obstruct
```

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

---

## 🧩 快速开始

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

```python
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](LICENSE)

---

## 🙏 致谢

本项目源自 [HydrogenLib](https://github.com/LittleNightSong/HydrogenLib) 的 `Objective-Struct` 模块，现已独立维护。