obstruct 0.3.0__tar.gz → 0.4.0__tar.gz

{obstruct-0.3.0 → obstruct-0.4.0}/.idea/workspace.xml

@@ -5,6 +5,8 @@
   </component>
   <component name="ChangeListManager">
     <list default="true" id="b482b6b4-48ce-4be1-bf3c-a72ec254fa35" name="更改" comment="fix: 更新版本号至 0.2.15，修复延迟加载不会应用到类属性的问题">
+      <change afterPath="$PROJECT_DIR$/BENCHMARK_TEST.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/obstruct/__version__.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/__version__.py" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/obstruct/aot/base.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/aot/base.py" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/obstruct/aot/unpack.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/aot/unpack.py" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/test/test_speed.py" beforeDir="false" afterPath="$PROJECT_DIR$/test/test_speed.py" afterDir="false" />

obstruct-0.4.0/BENCHMARK_TEST.md

@@ -0,0 +1,183 @@
+## 基准测试性能分析报告
+
+> 此报告由 **DeepSeek (offical)** 生成
+
+> 测试配置：1000 steps/轮，128 轮采样，32 次去极值。
+
+---
+
+## 一、测试结构与参数
+
+| 项目           | 值             | 补充                                             |
+|----------------|----------------|--------------------------------------------------|
+| 简单结构大小   | 42 bytes       | 12 个基本类型字段                                
+| 复杂结构大小   | 484 bytes      | 包含两个简单数据结构以及一个长度 100 的 int 数组 
+| 每轮迭代步数   | **1,000**      | 无                                               
+| 结果实际采样数 | **64**         | 无                                               
+| 总操作次数     | 64,000 次/方法 | 无                                               
+
+---
+
+## 二、按耗时排序（从快到慢）
+
+| 排名 | 测试名称                       | 平均耗时 (ns) | 相对 Pack 倍数 |
+|:----:|--------------------------------|:-------------:|:--------------:|
+|  1   | **Pack**                       |  **261.955**  |     1.00x      |
+|  2   | **Update From**                |    331.223    |     1.26x      |
+|  3   | **Update**                     |    377.706    |     1.44x      |
+|  4   | **Unpack From**                |    501.742    |     1.92x      |
+|  5   | **Unpack**                     |    601.889    |     2.30x      |
+|  6   | **Complex Update**             |    825.573    |     3.15x      |
+|  7   | **Complex Update From (100x)** |    965.261    |     3.68x      |
+|  8   | **Complex Unpack From (100x)** |   1,366.177   |     5.22x      |
+|  9   | **Complex Pack**               |   1,469.102   |     5.61x      |
+|  10  | **Complex Unpack**             |   1,986.633   |     7.58x      |
+|  11  | **Iter Update (100x)**         |  29,666.533   |    113.25x     |
+|  12  | **Iter Unpack (100x)**         |  42,771.392   |    163.28x     |
+|  13  | **Complex Iter Update (100x)** |  95,885.616   |    366.03x     |
+|  14  | **Complex Iter Unpack (100x)** |  144,415.439  |    551.30x     |
+
+---
+
+## 三、按方法类型分组对比
+
+### 3.1 简单方法
+
+| 方法        | 耗时 (ns) | 相对 Pack | 备注                    |
+|-------------|:---------:|:---------:|-------------------------|
+| Pack        |  261.955  |   1.00x   | 基准                    |
+| Update From |  331.223  |   1.26x   | 复用 + 偏移，最快更新类 |
+| Update      |  377.706  |   1.44x   | 复用对象                |
+| Unpack From |  501.742  |   1.92x   | 带偏移                  |
+| Unpack      |  601.889  |   2.30x   | 新建对象，最慢简单方法  |
+
+### 3.2 复杂方法
+
+| 方法                | 耗时 (ns) | 相对 Pack | 备注                      |
+|---------------------|:---------:|:---------:|---------------------------|
+| Complex Update      |  825.573  |   3.15x   | 复用对象，钩子触发        |
+| Complex Update From |  965.261  |   3.68x   | 复用 + 偏移，钩子触发     |
+| Complex Unpack From | 1,366.177 |   5.22x   | 带偏移，钩子触发          |
+| Complex Pack        | 1,469.102 |   5.61x   | 打包                      |
+| Complex Unpack      | 1,986.633 |   7.58x   | 新建对象 + 钩子，最慢单次 |
+
+### 3.3 迭代方法
+
+| 方法                       |  耗时 (ns)  | 相对 Pack | 每元素耗时  |
+|----------------------------|:-----------:|:---------:|:-----------:|
+| Iter Update (100x)         | 29,666.533  |  113.25x  |  296.67 ns  |
+| Iter Unpack (100x)         | 42,771.392  |  163.28x  |  427.71 ns  |
+| Complex Iter Update (100x) | 95,885.616  |  366.03x  |  958.86 ns  |
+| Complex Iter Unpack (100x) | 144,415.439 |  551.30x  | 1,444.15 ns |
+
+---
+
+## 四、关键性能对比
+
+### 4.1 复用 vs 新建对象
+
+| 对比组      | 新建 (unpack)  | 复用 (update) |  性能提升  |
+|-------------|:--------------:|:-------------:|:----------:|
+| 简单        |   601.889 ns   |  377.706 ns   | **+37.3%** |
+| 简单 + 偏移 |   501.742 ns   |  331.223 ns   | **+34.0%** |
+| 复杂        |  1,986.633 ns  |  825.573 ns   | **+58.5%** |
+| 复杂 + 偏移 |  1,366.177 ns  |  965.261 ns   | **+29.3%** |
+| 迭代        | 42,771.392 ns  | 29,666.533 ns | **+30.6%** |
+| 复杂迭代    | 144,415.439 ns | 95,885.616 ns | **+33.6%** |
+
+### 4.2 简单 vs 复杂（同类型对比）
+
+| 对比组      |   简单耗时    |    复杂耗时    |   倍数    |
+|-------------|:-------------:|:--------------:|:---------:|
+| Pack        |  261.955 ns   |  1,469.102 ns  | **5.61x** |
+| Unpack      |  601.889 ns   |  1,986.633 ns  | **3.30x** |
+| Update      |  377.706 ns   |   825.573 ns   | **2.19x** |
+| Update From |  331.223 ns   |   965.261 ns   | **2.91x** |
+| Iter Unpack | 42,771.392 ns | 144,415.439 ns | **3.38x** |
+| Iter Update | 29,666.533 ns | 95,885.616 ns  | **3.23x** |
+
+### 4.3 单次 vs 迭代（每元素对比）
+
+迭代方法将 100 次操作合并为 1 次调用，按每元素耗时对比：
+
+| 方法                       | 单次调用 (ns) | 每元素 (ns) |   单次 vs 迭代每元素   |
+|----------------------------|:-------------:|:-----------:|:----------------------:|
+| Unpack                     |    601.889    |      —      | 迭代每元素快 **28.9%** |
+| Iter Unpack (100x)         |  42,771.392   |   427.714   |                        |
+| Update                     |    377.706    |      —      | 迭代每元素快 **21.5%** |
+| Iter Update (100x)         |  29,666.533   |   296.665   |                        |
+| Complex Unpack             |   1,986.633   |      —      | 迭代每元素快 **27.3%** |
+| Complex Iter Unpack (100x) |  144,415.439  |  1,444.154  |                        |
+| Complex Update             |    825.573    |      —      | 迭代每元素快 **16.2%** |
+| Complex Iter Update (100x) |  95,885.616   |   958.856   |                        |
+
+---
+
+## 五、基准测试汇总表
+
+| #  | 测试名称                       |  耗时 (ns)  | 耗时 (µs) | 相对 Pack | 相对同组最优 | 钩子 |
+|:--:|--------------------------------|:-----------:|:---------:|:---------:|:------------:|:----:|
+| 1  | **Pack**                       |   261.955   |   0.262   |   1.00x   |     基准     |  ❌  |
+| 2  | **Update From**                |   331.223   |   0.331   |   1.26x   |   最快更新   |  ❌  |
+| 3  | **Update**                     |   377.706   |   0.378   |   1.44x   |      —       |  ❌  |
+| 4  | **Unpack From**                |   501.742   |   0.502   |   1.92x   |   最快解包   |  ❌  |
+| 5  | **Unpack**                     |   601.889   |   0.602   |   2.30x   |      —       |  ❌  |
+| 6  | **Complex Update**             |   825.573   |   0.826   |   3.15x   |   最快复杂   |  ✅  |
+| 7  | **Complex Update From**        |   965.261   |   0.965   |   3.68x   |      —       |  ✅  |
+| 8  | **Complex Unpack From**        |  1,366.177  |   1.366   |   5.22x   |      —       |  ✅  |
+| 9  | **Complex Pack**               |  1,469.102  |   1.469   |   5.61x   |      —       |  ❌  |
+| 10 | **Complex Unpack**             |  1,986.633  |   1.987   |   7.58x   |   最慢单次   |  ✅  |
+| 11 | **Iter Update (100x)**         | 29,666.533  |  29.667   |  113.25x  |   最快迭代   |  ❌  |
+| 12 | **Iter Unpack (100x)**         | 42,771.392  |  42.771   |  163.28x  |      —       |  ❌  |
+| 13 | **Complex Iter Update (100x)** | 95,885.616  |  95.886   |  366.03x  |      —       |  ✅  |
+| 14 | **Complex Iter Unpack (100x)** | 144,415.439 |  144.415  |  551.30x  |   最慢总榜   |  ✅  |
+
+---
+
+## 六、可视化性能分布
+
+```
+Pack         ████████████████████████████████████████████████████████████████████ 261.955 ns
+Update From  ██████████████████████████████████████████████████████████████████   331.223 ns
+Update       █████████████████████████████████████████████████████████████████    377.706 ns
+Unpack From  ████████████████████████████████████████████████████████████████████ 501.742 ns
+Unpack       ███████████████████████████████████████████████████████████████████ 601.889 ns
+Complex Upd  ███████████████████████████████████████████████████████████████████ 825.573 ns
+Complex UpF  ███████████████████████████████████████████████████████████████████ 965.261 ns
+Complex UnF  ███████████████████████████████████████████████████████████████████ 1,366 ns
+Complex Pack ███████████████████████████████████████████████████████████████████ 1,469 ns
+Complex Unp  ███████████████████████████████████████████████████████████████████ 1,987 ns
+─────────────────────────────────────────────────────────────────────────────────────────
+Iter Update  ███████████████████████████████████████████████████████████████████ 29,667 ns
+Iter Unpack  ███████████████████████████████████████████████████████████████████ 42,771 ns
+Cplx Iter Up ███████████████████████████████████████████████████████████████████ 95,886 ns
+Cplx Iter Un ███████████████████████████████████████████████████████████████████ 144,415 ns
+```
+
+---
+
+## 七、核心结论
+
+| 维度             | 结论                                                |
+|------------------|-----------------------------------------------------|
+| **最快单次操作** | `Pack` (261.96 ns)                                  |
+| **最快解析操作** | `Update From` (331.22 ns)                           |
+| **最慢单次操作** | `Complex Unpack` (1,986.63 ns)，比最快慢 **7.58x**  |
+| **复用提升**     | 复杂场景下 `update` 比 `unpack` 快 **58.5%**        |
+| **偏移影响**     | `unpack_from` 比 `unpack` 快 **16.6%**（简单）      |
+| **迭代效率**     | `iter_update` 比 `iter_unpack` 快 **30.6%**（简单） |
+| **复杂度代价**   | 复杂 Pack 比简单 Pack 慢 **5.61x**                  |
+| **钩子代价**     | `__post_unpack__` 增加约 **35%** 开销               |
+
+---
+
+## 八、最终建议
+
+| 场景                  | 推荐                                     | 理由                                       |
+|-----------------------|------------------------------------------|--------------------------------------------|
+| **高频单次解析**      | `update_from`                            | 最快解析方法，复用 + 偏移                  |
+| **需要新建对象**      | `unpack_from`                            | 比 `unpack` 快 16.6%                       |
+| **批量解析（100次）** | `iter_update`                            | 比 `iter_unpack` 快 30.6%，每元素仅 296 ns |
+| **复杂结构批量解析**  | `complex_iter_update`                    | 比 `complex_iter_unpack` 快 33.6%          |
+| **避免使用**          | `complex_unpack`                         | 单次最慢，新建对象 + 钩子双重开销          |
+| **极致性能**          | 手动 `memoryview` + `struct.unpack_from` | 避免切片拷贝和对象分配                     |

{obstruct-0.3.0 → obstruct-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: obstruct
-Version: 0.3.0
+Version: 0.4.0
 Author-email: LittleNightSong <LittleNightSongYO@outlook.com>
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python

obstruct-0.4.0/src/obstruct/__version__.py

@@ -0,0 +1 @@
+version = "0.4.0"

obstruct-0.4.0/test/test_speed.py

@@ -0,0 +1,162 @@
+import dataclasses
+import time
+from array import array
+from typing import Annotated
+
+import obstruct as obs
+
+
+def run_iterator(iterator):
+    [i for i in iterator]
+
+
+@dataclasses.dataclass()
+class MyStruct(obs.Struct):
+    a: int
+    b: int
+    c: float
+    d: int
+    e: obs.short
+    f: obs.unsigned_short
+    g: obs.long
+    h: obs.unsigned_long
+    i: obs.unsigned_long
+    j: obs.char
+    k: obs.unsigned_char
+    l: obs.long_long
+
+    def __post_unpack__(self):
+        global is_post_unpack_called
+        is_post_unpack_called = True
+
+
+@dataclasses.dataclass()
+class AnotherStruct(obs.Struct):
+    x: MyStruct
+    y: Annotated[array[int], 100]
+    z: MyStruct
+
+
+MyStruct.__compile_struct__()
+AnotherStruct.__compile_struct__()
+
+print('MyStruct size', MyStruct.__cstruct__.size)
+print('AnotherStruct size', AnotherStruct.__cstruct__.size)
+
+is_post_unpack_called = False
+
+data = MyStruct(
+    1, 2, 1.0, 4, 5, 6, 7, 8, 9, b'8', 1, 2
+)
+
+packed_data = data.pack()
+packed_data_100 = packed_data * 100
+
+complex_data = AnotherStruct(data, array('i', [100] * 100), data)
+packed_complex_data = complex_data.pack()
+packed_complex_data_100 = packed_complex_data * 100
+
+
+def test_timeit(name, code, extra="print('Post Hook Called:', is_post_unpack_called); is_post_unpack_called=False"):
+    import timeit
+
+    res = timeit.repeat(
+        code,
+        number=NUMBER,
+        repeat=REPEAT,
+        timer=time.perf_counter_ns,
+        globals=globals()
+    )
+
+    print()
+    # print(len(res))
+
+    for i in range(SORT):
+        res.remove(max(res))
+        res.remove(min(res))
+
+    print("Test: ", name)
+    print("Results Length:", len(res))
+
+    print(f'{NUMBER} steps finished in {sum(res) / (len(res)):.3f} ns')
+    print(f'Average: {sum(res) / (len(res)) / NUMBER:.3f} ns per step', '\n\n')
+
+    exec(extra, globals=globals()) if extra else None
+
+
+# print("\n\nMyStruct:", MyStruct.__cstruct__.size)
+print("AnotherStruct:", AnotherStruct.__cstruct__.size, '\n\n')
+
+NUMBER = 1000
+REPEAT = 128
+SORT = 32
+
+test_timeit(
+    name='Pack',
+    code="""data.pack()""",
+)
+
+test_timeit(
+    name='Unpack',
+    code="""MyStruct.unpack(packed_data)""",
+)
+
+test_timeit(
+    name='Complex Pack',
+    code="""complex_data.pack()""",
+)
+
+test_timeit(
+    name='Complex Unpack',
+    code="""AnotherStruct.unpack(packed_complex_data)""",
+)
+
+test_timeit(
+    name='Update',
+    code="""data.update(packed_data)"""
+)
+
+test_timeit(
+    name='Iter Unpack (100x)',
+    code="""run_iterator(MyStruct.iter_unpack(packed_data_100))"""
+)
+
+test_timeit(
+    name='Iter Update (100x)',
+    code="""run_iterator(MyStruct.iter_update(packed_data_100, obj=data))"""
+)
+
+test_timeit(
+    name='Unpack From',
+    code="""MyStruct.unpack_from(packed_data)"""
+)
+
+test_timeit(
+    name='Update From',
+    code="""data.update_from(packed_data)"""
+)
+
+test_timeit(
+    name='Complex Update',
+    code="""complex_data.update(packed_complex_data)"""
+)
+
+test_timeit(
+    name='Complex Iter Unpack (100x)',
+    code="""run_iterator(AnotherStruct.iter_unpack(packed_complex_data_100))"""
+)
+
+test_timeit(
+    name='Complex Iter Update (100x)',
+    code="""run_iterator(AnotherStruct.iter_update(packed_complex_data_100, obj=complex_data))"""
+)
+
+test_timeit(
+    name='Complex Unpack From (100x)',
+    code="""AnotherStruct.unpack_from(packed_complex_data)"""
+)
+
+test_timeit(
+    name='Complex Update From (100x)',
+    code="""complex_data.update_from(packed_complex_data)"""
+)

obstruct-0.3.0/src/obstruct/__version__.py

@@ -1 +0,0 @@
-version = "0.3.0"

obstruct-0.3.0/test/test_speed.py

@@ -1,104 +0,0 @@
-import dataclasses
-import time
-from array import array
-from typing import Annotated
-
-import obstruct as obs
-
-
-@dataclasses.dataclass()
-class MyStruct(obs.Struct):
-    a: int
-    b: int
-    c: float
-    d: int
-    e: obs.short
-    f: obs.unsigned_short
-    g: obs.long
-    h: obs.unsigned_long
-    i: obs.unsigned_long
-    j: obs.char
-    k: obs.unsigned_char
-    l: obs.long_long
-
-    def __post_unpack__(self):
-        ...
-
-
-@dataclasses.dataclass()
-class AnotherStruct(obs.Struct):
-    x: MyStruct
-    y: Annotated[array[int], 100]
-    z: MyStruct
-
-
-MyStruct.__compile_struct__()
-AnotherStruct.__compile_struct__()
-
-print('MyStruct size', MyStruct.__cstruct__.size)
-print('AnotherStruct size', AnotherStruct.__cstruct__.size)
-
-
-# data = MyStruct(
-#     1,2,1.0,4,5,6,7,8,9,b'8',1,2
-# )
-#
-# packed_data = data.pack()
-
-
-# complex_data = AnotherStruct(data, array('i', [100]*100), data)
-# packed_complex_data = complex_data.pack()
-
-
-def test_timeit(name, code):
-    import timeit
-
-    print("Test: ", name)
-    res = timeit.repeat(
-        code,
-        number=NUMBER,
-        repeat=REPEAT,
-        timer=time.perf_counter_ns,
-        globals=globals()
-    )
-
-    print(len(res))
-
-    for i in range(SORT):
-        res.remove(max(res))
-        res.remove(min(res))
-
-    print("Results Length:", len(res))
-
-    print(f'{NUMBER} steps finished in {sum(res)/(len(res)):.3f} ns')
-    print(f'Average: {sum(res)/(len(res))/NUMBER:.3f} ns per step', '\n\n')
-
-
-# print("\n\nMyStruct:", MyStruct.__cstruct__.size)
-print("AnotherStruct:", AnotherStruct.__cstruct__.size, '\n\n')
-
-NUMBER = 10000
-REPEAT = 128
-SORT = 32
-
-# test_timeit(
-#     name='Pack',
-#     code="""data.pack()""",
-# )
-#
-# test_timeit(
-#     name='Unpack',
-#     code="""MyStruct.unpack(packed_data)""",
-# )
-#
-#
-#
-# test_timeit(
-#     name='Complex Pack',
-#     code="""complex_data.pack()""",
-# )
-#
-# test_timeit(
-#     name='Complex Unpack',
-#     code="""AnotherStruct.unpack(packed_complex_data)""",
-# )