obstruct 0.2.3__tar.gz → 0.2.5__tar.gz

obstruct-0.2.5/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/obstruct.iml" filepath="$PROJECT_DIR$/.idea/obstruct.iml" />
+    </modules>
+  </component>
+</project>

obstruct-0.2.3/.idea/Hydrogenlib-Objective-Struct.iml → obstruct-0.2.5/.idea/obstruct.iml

@@ -2,16 +2,13 @@
 <module external.system.id="pyproject.toml" type="PYTHON_MODULE" version="4">
   <component name="NewModuleRootManager">
     <content url="file://$MODULE_DIR$">
-      <sourceFolder url="file://$MODULE_DIR$/src" />
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
       <excludeFolder url="file://$MODULE_DIR$/.venv" />
     </content>
     <orderEntry type="jdk" jdkName="E:\.projects\obstruct\.venv" jdkType="Python SDK" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>
-  <component name="PackageRequirementsSettings" />
   <component name="PyDocumentationSettings">
     <option name="format" value="PLAIN" />
   </component>
-  <component name="ReSTService" />
-  <component name="TestRunnerService" />
 </module>

{obstruct-0.2.3 → obstruct-0.2.5}/.idea/workspace.xml

@@ -4,15 +4,15 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="b482b6b4-48ce-4be1-bf3c-a72ec254fa35" name="更改" comment="initial commit">
-      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+    <list default="true" id="b482b6b4-48ce-4be1-bf3c-a72ec254fa35" name="更改" comment="增强 array 类型的支持">
+      <change beforePath="$PROJECT_DIR$/src/obstruct/__init__.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/__init__.py" 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/pack.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/aot/pack.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$/src/obstruct/decorator.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/decorator.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/obstruct/methods.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/methods.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/obstruct/types/types.pyi" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/types/types.pyi" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/uv.lock" beforeDir="false" afterPath="$PROJECT_DIR$/uv.lock" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/obstruct/decorator.py" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/obstruct/struct_type.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/obstruct/struct_type.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/test/test_speed.py" beforeDir="false" afterPath="$PROJECT_DIR$/test/test_speed.py" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -29,22 +29,22 @@
   <component name="Git.Settings">
     <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
   </component>
-  <component name="GitHubPullRequestSearchHistory"><![CDATA[{
-  "lastFilter": {
-    "state": "OPEN",
-    "assignee": "LittleNightSong"
+  <component name="GitHubPullRequestSearchHistory">{
+  &quot;lastFilter&quot;: {
+    &quot;state&quot;: &quot;OPEN&quot;,
+    &quot;assignee&quot;: &quot;LittleNightSong&quot;
   }
-}]]></component>
-  <component name="GithubPullRequestsUISettings"><![CDATA[{
-  "selectedUrlAndAccountId": {
-    "url": "https://github.com/LittleNightSong/obstruct.git",
-    "accountId": "c74c50b1-2437-429b-b395-d763b566b8a2"
+}</component>
+  <component name="GithubPullRequestsUISettings">{
+  &quot;selectedUrlAndAccountId&quot;: {
+    &quot;url&quot;: &quot;https://github.com/LittleNightSong/obstruct.git&quot;,
+    &quot;accountId&quot;: &quot;c74c50b1-2437-429b-b395-d763b566b8a2&quot;
   }
-}]]></component>
-  <component name="ProjectColorInfo"><![CDATA[{
-  "associatedIndex": 3,
-  "fromUser": false
-}]]></component>
+}</component>
+  <component name="ProjectColorInfo">{
+  &quot;associatedIndex&quot;: 3,
+  &quot;fromUser&quot;: false
+}</component>
   <component name="ProjectId" id="3HzAgHvw3X1T2NidzBlYQSHnZow" />
   <component name="ProjectViewState">
     <option name="hideEmptyMiddlePackages" value="true" />
@@ -56,6 +56,7 @@
     "Python.test.executor": "Run",
     "Python.test_speed.executor": "Run",
     "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.git.unshallow": "true",
     "RunOnceActivity.typescript.service.memoryLimit.init": "true",
     "codeWithMe.voiceChat.enabledByDefault": "false",
     "git-widget-placeholder": "main",
@@ -71,7 +72,7 @@
 }]]></component>
   <component name="RunManager" selected="Python.test_speed">
     <configuration name="test" type="PythonConfigurationType" factoryName="Python" temporary="true" nameIsGenerated="true">
-      <module name="Hydrogenlib-Objective-Struct" />
+      <module name="obstruct" />
       <option name="ENV_FILES" value="" />
       <option name="INTERPRETER_OPTIONS" value="" />
       <option name="PARENT_ENVS" value="true" />
@@ -95,7 +96,7 @@
       <method v="2" />
     </configuration>
     <configuration name="test_speed" type="PythonConfigurationType" factoryName="Python" temporary="true" nameIsGenerated="true">
-      <module name="Hydrogenlib-Objective-Struct" />
+      <module name="obstruct" />
       <option name="ENV_FILES" value="" />
       <option name="INTERPRETER_OPTIONS" value="" />
       <option name="PARENT_ENVS" value="true" />
@@ -148,7 +149,39 @@
       <option name="project" value="LOCAL" />
       <updated>1786865208583</updated>
     </task>
-    <option name="localTasksCounter" value="2" />
+    <task id="LOCAL-00002" summary="增强类型系统，撰写 README.md">
+      <option name="closed" value="true" />
+      <created>1786868730474</created>
+      <option name="number" value="00002" />
+      <option name="presentableId" value="LOCAL-00002" />
+      <option name="project" value="LOCAL" />
+      <updated>1786868730474</updated>
+    </task>
+    <task id="LOCAL-00003" summary="补充：基准测试脚本">
+      <option name="closed" value="true" />
+      <created>1786868746817</created>
+      <option name="number" value="00003" />
+      <option name="presentableId" value="LOCAL-00003" />
+      <option name="project" value="LOCAL" />
+      <updated>1786868746817</updated>
+    </task>
+    <task id="LOCAL-00004" summary="修正了一些命名">
+      <option name="closed" value="true" />
+      <created>1786870314349</created>
+      <option name="number" value="00004" />
+      <option name="presentableId" value="LOCAL-00004" />
+      <option name="project" value="LOCAL" />
+      <updated>1786870314349</updated>
+    </task>
+    <task id="LOCAL-00005" summary="增强 array 类型的支持">
+      <option name="closed" value="true" />
+      <created>1786875274813</created>
+      <option name="number" value="00005" />
+      <option name="presentableId" value="LOCAL-00005" />
+      <option name="project" value="LOCAL" />
+      <updated>1786875274813</updated>
+    </task>
+    <option name="localTasksCounter" value="6" />
     <servers />
   </component>
   <component name="TypeScriptGeneratedFilesManager">
@@ -167,6 +200,10 @@
   </component>
   <component name="VcsManagerConfiguration">
     <MESSAGE value="initial commit" />
-    <option name="LAST_COMMIT_MESSAGE" value="initial commit" />
+    <MESSAGE value="增强类型系统，撰写 README.md" />
+    <MESSAGE value="补充：基准测试脚本" />
+    <MESSAGE value="修正了一些命名" />
+    <MESSAGE value="增强 array 类型的支持" />
+    <option name="LAST_COMMIT_MESSAGE" value="增强 array 类型的支持" />
   </component>
 </project>

{obstruct-0.2.3 → obstruct-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: obstruct
-Version: 0.2.3
+Version: 0.2.5
 Author-email: LittleNightSong <LittleNightSongYO@outlook.com>
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python
@@ -15,42 +15,48 @@ Description-Content-Type: text/markdown
 _来自已弃坑的 `Hydrogenlib`，重拾起当初的决心_
 
 
->[!TIP]
+> [!TIP]
 > 这个项目来自 [`HydrogenLib`](https://github.com/LittleNightSong/HydrogenLib)的 `Objective-Struct` 模块，脱离大项目的版本
 >
 > 同时，`HydrogenLib`中的 `Objective-Struct` 不再会更新
 
->[!TIP]
+> [!TIP]
 > 作者的主要开发精力放在了另一些项目上，也许很长时间这个项目都不会再更新
 
 # OBStruct
+
 _一个简单、纯粹、极速的二进制解析库_
 
 ## 亮点
+
 - 纯 Python
 - 基于类型注解的字段声明方式
 - 支持 `struct` 标准库中的所有格式，并额外支持 array 类型
 - 基于 AOT 的加速
 - 完整的操作支持（打包、解包、流式处理）
 
->[!WARNING]
->使用 `array` 类型将带来严重的性能损失，谨慎使用
+> [!WARNING]
+>使用 `array` 类型时，建议不要传入 list 类型或其它 Python 序列，
+> 可能会带来极大的性能影响
 
 ## 基准测试
+
 ### 系统环境
-- 12th Gen Intel® Core(TM) i7-12700H
+
+- 12th Gen Intel® Core (TM) i7-12700H
 
 在 12个字段，10000 次操作，8轮取平均值的条件下：
+
 - 打包：269.639ns 一次操作
 - 解包：582.185ns 一次操作
 
-
 ## 安装
+
 ```commandline
 pip install obstruct
 ```
-如果使用 `uv` 等包管理器，则按照工具的方法安装即可
 
+如果使用 `uv` 等包管理器，则按照工具的方法安装即可
 
 ## 用法
 
@@ -60,6 +66,7 @@ pip install obstruct
 import obstruct as obs
 from dataclasses import dataclass
 
+
 @obs.struct()
 @dataclass()
 class MyStruct(obs.Struct):
@@ -68,24 +75,24 @@ class MyStruct(obs.Struct):
     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)
 
 ```
 
-在上述示例中，你可能发现 `data != restored`，这是浮点数的精度限制导致的。
-因此，我们不建议使用浮点数类型，浮点数在二进制传输中也不常见。
+在上述示例中，你可能发现 `data != restored`，这是浮点数的精度限制导致的。 因此，我们不建议使用浮点数类型，浮点数在二进制传输中也不常见。
 
 ## 计划
+
 - 展平装饰器，目前的 API 较为繁琐，需要简化为唯一的 `Struct` 基类
 - 继续优化性能
 - 通过存根文件强制表明类型似乎变得不再有效了

{obstruct-0.2.3 → obstruct-0.2.5}/README.md

@@ -1,42 +1,48 @@
 _来自已弃坑的 `Hydrogenlib`，重拾起当初的决心_
 
 
->[!TIP]
+> [!TIP]
 > 这个项目来自 [`HydrogenLib`](https://github.com/LittleNightSong/HydrogenLib)的 `Objective-Struct` 模块，脱离大项目的版本
 >
 > 同时，`HydrogenLib`中的 `Objective-Struct` 不再会更新
 
->[!TIP]
+> [!TIP]
 > 作者的主要开发精力放在了另一些项目上，也许很长时间这个项目都不会再更新
 
 # OBStruct
+
 _一个简单、纯粹、极速的二进制解析库_
 
 ## 亮点
+
 - 纯 Python
 - 基于类型注解的字段声明方式
 - 支持 `struct` 标准库中的所有格式，并额外支持 array 类型
 - 基于 AOT 的加速
 - 完整的操作支持（打包、解包、流式处理）
 
->[!WARNING]
->使用 `array` 类型将带来严重的性能损失，谨慎使用
+> [!WARNING]
+>使用 `array` 类型时，建议不要传入 list 类型或其它 Python 序列，
+> 可能会带来极大的性能影响
 
 ## 基准测试
+
 ### 系统环境
-- 12th Gen Intel® Core(TM) i7-12700H
+
+- 12th Gen Intel® Core (TM) i7-12700H
 
 在 12个字段，10000 次操作，8轮取平均值的条件下：
+
 - 打包：269.639ns 一次操作
 - 解包：582.185ns 一次操作
 
-
 ## 安装
+
 ```commandline
 pip install obstruct
 ```
-如果使用 `uv` 等包管理器，则按照工具的方法安装即可
 
+如果使用 `uv` 等包管理器，则按照工具的方法安装即可
 
 ## 用法
 
@@ -46,6 +52,7 @@ pip install obstruct
 import obstruct as obs
 from dataclasses import dataclass
 
+
 @obs.struct()
 @dataclass()
 class MyStruct(obs.Struct):
@@ -54,24 +61,24 @@ class MyStruct(obs.Struct):
     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)
 
 ```
 
-在上述示例中，你可能发现 `data != restored`，这是浮点数的精度限制导致的。
-因此，我们不建议使用浮点数类型，浮点数在二进制传输中也不常见。
+在上述示例中，你可能发现 `data != restored`，这是浮点数的精度限制导致的。 因此，我们不建议使用浮点数类型，浮点数在二进制传输中也不常见。
 
 ## 计划
+
 - 展平装饰器，目前的 API 较为繁琐，需要简化为唯一的 `Struct` 基类
 - 继续优化性能
 - 通过存根文件强制表明类型似乎变得不再有效了

{obstruct-0.2.3 → obstruct-0.2.5}/src/obstruct/__init__.py

@@ -1,4 +1,3 @@
 from .methods import pack, unpack
-from .decorator import struct
 from .struct_type import Struct
 from .types import *

obstruct-0.2.5/src/obstruct/__version__.py

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

{obstruct-0.2.3 → obstruct-0.2.5}/src/obstruct/aot/base.py

@@ -5,7 +5,6 @@ import itertools
 import typing
 from typing import Any
 
-from obstruct.methods import get_ctype
 
 
 class _objective_node_operator:
@@ -31,18 +30,21 @@ class _objective_node_operator:
             self._node.body.append(tree)
             return tree
 
-    # def insert_code(self, index, code: str):
-    #     tree = ast.parse(code)
-    #     if isinstance(tree, ast.Module):
-    #         for node in reversed(tree.body):
-    #             self._node.body.insert(index, node)
-    #         return tree
-    #     elif isinstance(tree, ast.Expr):
-    #         self._node.body.insert(index, tree.value)
-    #         return tree.value
-    #     else:
-    #         self._node.body.insert(index, tree)
-    #         return tree
+    def add_codes(self, codes: typing.Iterable[str]):
+        [self.add_code(c) for c in codes]
+
+    def insert_code(self, index, code: str):
+        tree = ast.parse(code)
+        if isinstance(tree, ast.Module):
+            for node in reversed(tree.body):
+                self._node.body.insert(index, node)
+            return tree
+        elif isinstance(tree, ast.Expr):
+            self._node.body.insert(index, tree.value)
+            return tree.value
+        else:
+            self._node.body.insert(index, tree)
+            return tree
 
     def compile(self):
         module = ast.Module([self._node])
@@ -54,6 +56,7 @@ class _objective_node_operator:
     def exec(self, globals=None, locals=None, closure=None):
         globals = globals or {}
         exec(self.compile(), globals, locals, closure=closure)
+        # print(repr(globals))
         return globals[self._node.name]
 
     def generate_code(self):
@@ -134,8 +137,13 @@ def get_array_spec(tp):
 
 
 def get_array_ctype(tp) -> str | None | Any:
+    from obstruct.methods import get_ctype
     return get_ctype(get_array_spec(tp)[0])
 
 
+def get_array_length(tp):
+    return get_array_spec(tp)[1]
+
+
 def to_tuple_expression(names, prefix='self.'):
     return ', '.join(f'{prefix}{name}' for name in names)

obstruct-0.2.5/src/obstruct/aot/pack.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import array
+import struct
+import typing
+
+from .base import unique_name_generator, is_struct, is_array, get_array_ctype, to_tuple_expression, function_def, \
+    get_array_length
+
+if typing.TYPE_CHECKING:
+    from .. import struct_type
+
+
+def create_pack_methods(cls: type[struct_type.Struct]):
+    """
+    Generate `pack` and `pack_into` method
+    """
+    from obstruct.methods import get_ctype
+    with (
+        function_def('pack(self)') as pack,
+        function_def('pack_into(self, buffer, offset=0)') as pack_into,
+    ):
+        ung = unique_name_generator()
+        flat_fields = []
+        array_fields = []
+
+        def add_code(code):
+            pack.add_code(code)
+            pack_into.add_code(code)
+
+        def walk(fields, path, parent_name=None, offset=0):
+            # parent name 标识了这个字段的父字段被赋值给了哪个临时变量，这样可以复用已有的临时变量，减少结构体属性访问次数
+            name = path[-1]  # 这里的 name 是默认的 self，如果当前处理的是内嵌的结构体，那么 name 会被替换成临时变量
+
+            if len(path) > 1:  # 当前处理的是内嵌结构体
+                name = next(ung)  # 生成一个临时变量缓存其值
+                add_code(f'{name} = {parent_name}.{path[-1]}')
+
+            for field in fields:  # 遍历结构体的所有字段
+                if is_struct(field.type):  # 又是一个内嵌的结构体字段
+                    walk(field.type.__cfields__, path + (field.name,), name, offset)  # 递归
+
+                elif is_array(field.type):  # 一个数组类型
+                    dtype = get_array_ctype(field.type)
+                    nbytes = struct.calcsize(dtype) * get_array_length(field.type)
+
+                    _ = next(ung)
+                    add_code(f'{_} = array({dtype!r}, {name}.{field.name})')
+                    # flat_fields.append(f'{_}.tobytes()')
+                    array_fields.append((_, offset, nbytes))
+
+                else:
+                    flat_fields.append(f'{name}.{field.name}')  # 普通的字段，添加到传递目标列表中
+
+                offset += struct.calcsize(get_ctype(field.type))
+
+        walk(cls.__cfields__, ('self',))  # 启动递归函数
+        # names = [field.name for field in fields]
+
+        expression = to_tuple_expression(flat_fields, prefix='')
+
+        if array_fields:  # 如果有数组字段，我们需要手动操作缓冲区
+            pack_into.insert_code(0, "buffer = memoryview(buffer)")
+            pack.add_code(f"buffer = bytearray({cls.__cstruct__.size})")  # 初始化缓冲区
+            for array_name, offset, size in array_fields:
+                add_code(f"buffer[{offset}:{offset + size}] = memoryview({array_name}).cast('B')")
+
+            pack.add_code(f"_pack_into(buffer, 0, {expression})")  # 返回打包的结果，将所有字段参数展开传递
+            pack.add_return("buffer")
+        else:
+            pack.add_return(f"_pack({expression})")
+
+        pack_into.add_code(f"_pack_into(buffer, offset, {expression})")
+        # print(pack.generate_code())  # Debug
+        # print(pack_into.generate_code())  # Debug
+        return (
+            pack.exec({'_pack': cls.__cstruct__.pack, '_pack_into': cls.__cstruct__.pack_into, 'array': array.array}),
+            pack_into.exec({'_pack_into': cls.__cstruct__.pack_into, 'array': array.array})
+        )