obstruct 0.2.1__py3-none-any.whl

obstruct/__init__.py

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

obstruct/__version__.py

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

obstruct/aot/__init__.py

@@ -0,0 +1,2 @@
+from .base import function_def
+from .aot import *

obstruct/aot/aot.py

@@ -0,0 +1,2 @@
+from .pack import create_pack_methods
+from .unpack import create_unpack_methods

obstruct/aot/base.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import ast
+import itertools
+import typing
+from typing import Any
+
+import typing_inspection.typing_objects
+
+from _hydrogenlib_core.typefunc import enhanced_generator
+from obstruct.methods import get_ctype
+
+
+class _objective_node_operator:
+    _node: ast.stmt
+
+    @property
+    def node(self):
+        return self._node
+
+    def add_node(self, node: ast.AST):
+        self._node.body.append(node)
+        return node
+
+    def add_code(self, code: str):
+        tree = ast.parse(code)
+        if isinstance(tree, ast.Module):
+            self._node.body.extend(tree.body)
+            return tree
+        elif isinstance(tree, ast.Expr):
+            self._node.body.append(tree.value)
+            return tree.value
+        else:
+            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 compile(self):
+        module = ast.Module([self._node])
+        ast.fix_missing_locations(module)
+        return compile(
+            module, filename="<string>", mode="exec"
+        )
+
+    def exec(self, globals=None, locals=None, closure=None):
+        globals = globals or {}
+        exec(self.compile(), globals, locals, closure=closure)
+        return globals[self._node.name]
+
+    def generate_code(self):
+        module = ast.Module([self._node])
+        ast.fix_missing_locations(module)
+        return ast.unparse(module)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+
+class function_def(_objective_node_operator):
+    def __init__(self, signature: str):
+        self._signature = signature
+        self._node = ast.parse(f'def {signature}: pass').body[0]  # type: ast.FunctionDef
+        self._node.body.clear()
+
+    def add_decorator(self, expr: str | ast.expr):
+        if isinstance(expr, str):
+            node = ast.parse(expr).body[0]
+
+            if not isinstance(node, ast.Expr):
+                raise ValueError(expr)
+
+            expr = node.value
+
+        self._node.decorator_list.append(expr)
+        return expr
+
+    def add_return(self, expr: str | ast.expr):
+        if isinstance(expr, str):
+            node = ast.parse(expr).body[0]
+            if not isinstance(node, ast.Expr):
+                raise ValueError(expr)
+            self._node.body.append(ast.Return(node.value))
+        else:
+            self._node.body.append(ast.Return(expr))
+
+
+class for_stmt(_objective_node_operator):
+    def __init__(self, expr):
+        self._node = ast.parse(f"for {expr}: ...").body[0]  # type: ast.For
+        self._node.body.clear()
+
+    def exec(self, globals=None, locals=None, closure=None):
+        return exec(self.compile(), globals, locals, closure=closure)
+
+
+available_characters = tuple(
+    chr(i) for i in range(65, 91)
+)
+
+
+@enhanced_generator(history=True)
+def unique_name_generator():
+    cnt = 0
+    while True:
+        cnt += 1
+        yield from map(lambda x: ''.join(x),
+                       itertools.combinations(available_characters, cnt))
+
+
+def is_struct(tp):
+    return hasattr(tp, '__cstruct__')
+
+
+def is_array(tp):
+    if typing_inspection.typing_objects.is_annotated(typing.get_origin(tp)):
+        return True
+    return False
+
+
+def get_array_spec(tp):
+    ls_type, length = typing.get_args(tp)
+    return typing.get_args(ls_type)[0], length
+
+
+def get_array_ctype(tp) -> str | None | Any:
+    return get_ctype(get_array_spec(tp)[0])
+
+
+def to_tuple_expression(names, prefix='self.'):
+    return ', '.join(f'{prefix}{name}' for name in names)

obstruct/aot/pack.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import array
+import typing
+
+from .base import unique_name_generator, is_struct, is_array, get_array_ctype, to_tuple_expression, function_def
+
+if typing.TYPE_CHECKING:
+    from .. import struct_type
+
+
+def create_pack_methods(cls: struct_type.Struct):
+    """
+    Generate `pack` and `pack_into` method
+    """
+    with (
+        function_def('pack(self)') as pack,
+        function_def('pack_into(self, buffer, offset=0)') as pack_into,
+    ):
+        ung = unique_name_generator()
+        flat_fields = []
+
+        def add_code(code):
+            pack.add_code(code)
+            pack_into.add_code(code)
+
+        def walk(fields, path, parent_name=None):
+            # parent name 标识了这个字段的父字段被赋值给了哪个临时变量，这样可以复用已有的临时变量，减少结构体属性访问次数
+            name = 'self'  # 这里的 name 是默认的 self，如果当前处理的是内嵌的结构体，那么 name 会被替换成临时变量
+
+            if len(path) > 1:  # 当前处理的是内嵌结构体
+                name = ung.next()  # 生成一个临时变量缓存其值
+                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)  # 递归
+                elif is_array(field.type):  # 一个数组类型
+                    d_ctype = get_array_ctype(field.type)
+
+                    _ = ung.next()
+                    add_code(f'{_} = array({d_ctype!r}, {name}.{field.name})')
+                    flat_fields.append(f'{_}.tobytes()')
+
+                else:
+                    flat_fields.append(f'{name}.{field.name}')  # 普通的字段，添加到传递目标列表中
+
+        walk(cls.__cfields__, ('self',))  # 启动递归函数
+        # names = [field.name for field in fields]
+
+        expression = to_tuple_expression(flat_fields, prefix='')
+        pack.add_return(f"xpack({expression})")  # 返回打包的结果，将所有字段参数展开传递
+        pack_into.add_code(f"xpack_into(buffer, offset, {expression})")
+        # print(pack.generate_code())  # Debug
+        return (
+            pack.exec({'xpack': cls.__cstruct__.pack, 'array': array.array}),
+            pack_into.exec({'xpack_into': cls.__cstruct__.pack_into, 'array': array.array})
+        )

obstruct/aot/unpack.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import array
+import typing
+
+from .base import unique_name_generator, is_struct, is_array, get_array_ctype, function_def, for_stmt
+
+if typing.TYPE_CHECKING:
+    from .. import struct_type
+
+
+def create_unpack_methods(cls: type[struct_type.Struct]):
+    with (
+        function_def('unpack(cls, buffer)') as unpack,
+        function_def('update(self, buffer)') as update,
+        function_def('unpack_from(cls, buffer, offset=0)') as unpack_from,
+        function_def('update_from(self, buffer, offset=0)') as update_from,
+        function_def('iter_unpack(cls, buffer)') as iter_unpack,
+        function_def('iter_update(cls, buffer, obj=None)') as iter_update,
+    ):
+        unpack.add_decorator('classmethod')  # unpack 是一个类方法
+        unpack_from.add_decorator('classmethod')  # unpack_from 也是
+        iter_unpack.add_decorator('classmethod')
+        iter_update.add_decorator('classmethod')
+
+        ung = unique_name_generator()
+
+        def update_add_code(code):
+            update.add_code(code)
+            update_from.add_code(code)
+            iter_update_inner.add_code(code)
+
+        def unpack_add_code(code):
+            unpack.add_code(code)
+            unpack_from.add_code(code)
+            iter_unpack_inner.add_code(code)
+
+        post_processors = []  # 后处理代码列表
+        assigns = []  # 赋值目标列表
+        inner_classes = {}  # 内嵌的结构体的类型映射（所有内嵌结构体的类型在生成代码时都会被代替为无意义的名称）
+
+        iter_update.add_code("self = cls() if obj is None else obj")
+
+        iter_unpack_inner = for_stmt("values in x_iter_unpack(buffer)")
+        iter_update_inner = for_stmt("values in x_iter_unpack(buffer)")
+
+        iter_unpack.add_node(iter_unpack_inner.node)
+        iter_update.add_node(iter_update_inner.node)
+
+        def walk(fields, path, parent_name=None, current_class_name='cls'):
+            name = 'self'
+
+            if len(path) > 1:  # 在处理内嵌的结构体
+                name = ung.next()  # 临时变量的名称
+                update_add_code(f"{name} = {parent_name}.{path[-1]}")
+
+                unpack_add_code(f"{parent_name}.{path[-1]} = {name} = __new__({current_class_name})")  # 组合赋值
+            else:
+                unpack_add_code(f"{name} = __new__({current_class_name})")  # 不需要临时变量存储根对象
+                # update 在这里不需要创建新对象
+
+            for field in fields:  # 遍历字段
+                field_ref = f'{name}.{field.name}'
+
+                if is_struct(field.type):  # 是个内嵌的结构体
+                    if field.type not in inner_classes:  # 如果这个内嵌的结构体类型不在已知的结构体中（没有分配类名称）
+                        type_name = ung.next()  # 生成一个唯一的类名
+                        inner_classes[field.type] = type_name  # 添加
+                    else:
+                        type_name = inner_classes[field.type]  # 如果在，那么提取
+
+                    walk(field.type.__cfields__, path + (field.name,), name, type_name)
+                elif is_array(field.type):
+                    d_ctype = get_array_ctype(field.type)
+                    post_processors.append(
+                        f'_ = array({d_ctype!r});'
+                        f'_.frombytes({field_ref});'
+                        f'{field_ref} = _'
+                    )
+                    assigns.append(field_ref)
+                else:
+                    assigns.append(field_ref)
+
+        walk(cls.__cfields__, ('A',))
+
+        assign_code = f"{', '.join(assigns)} = x_unpack(buffer)"  # 生成普通的 unpack, update 用的赋值语句
+        unpack.add_code(assign_code)
+        update.add_code(assign_code)
+
+        assign_code = assign_code.replace("x_unpack(buffer)", "values")  # 生成 iter_xxx 的赋值语句
+        iter_unpack_inner.add_code(assign_code)
+        iter_update_inner.add_code(assign_code)
+
+        assign_code = assign_code.replace("values", "x_unpack_from(buffer, offset)")  # 生成 xxx_from 的赋值语句
+        unpack_from.add_code(assign_code)
+        update_from.add_code(assign_code)
+
+        for post_processor in post_processors:
+            unpack_add_code(post_processor)
+            update_add_code(post_processor)
+
+        unpack.add_return('self')
+        update.add_return('self')
+        unpack_from.add_return('self')
+        update_from.add_return('self')
+
+        iter_unpack_inner.add_code('yield self')  # iter 方法是 yield，而非 return
+        iter_update_inner.add_code('yield self')
+
+        # print(unpack.generate_code())
+        # print(update.generate_code())
+        # print(unpack_from.generate_code())
+        # print(update_from.generate_code())
+        # print(iter_unpack.generate_code())
+        print(iter_update.generate_code())
+
+        globals = {
+            v: k for k, v in inner_classes.items()  # 翻转字典
+        }
+
+        globals.update(dict(
+            __new__=object.__new__,
+            x_unpack=cls.__cstruct__.unpack,
+            x_unpack_from=cls.__cstruct__.unpack_from,
+            x_iter_unpack=cls.__cstruct__.iter_unpack,
+            array=array.array
+        ))
+
+        return unpack.exec(
+            globals
+        ), update.exec(
+            globals
+        ), unpack_from.exec(
+            globals
+        ), update_from.exec(
+            globals
+        ), iter_unpack.exec(
+            globals
+        ), iter_update.exec(
+            globals
+        )

obstruct/decorator.py

@@ -0,0 +1,41 @@
+import dataclasses
+import typing
+
+from . import struct_type
+from .aot import pack, unpack
+from .methods import to_format_string
+
+endian_control_characters = tuple('<@=!>')
+
+
+def struct(maybe_cls=None, *, endian='@'):
+    def decorator[T](cls: T) -> type[struct_type.Struct]:
+        import struct
+
+        # module = sys.modules[cls.__module__]
+
+        fields = dataclasses.fields(cls)
+        # namesp = module.__dict__
+        # print(namesp)
+        real_annotations = typing.get_type_hints(cls)
+        # print(cls, real_annotations)
+
+        for field in fields:
+            print(cls, field.name, repr(field.type))
+            if isinstance(field.type, str):
+                field.type = real_annotations[field.name]
+
+        cls.__ctype__ = to_format_string([field.type for field in fields])
+        # print(cls.__ctype__)
+        cls.__cfields__ = tuple(fields)  # type: tuple[dataclasses.Field, ...]
+        cls.__cstruct__ = struct.Struct(endian + cls.__ctype__)  # 构造 Struct 类型
+        cls.__cendian__ = endian
+
+        cls.pack, cls.pack_into = pack.create_pack_methods(cls)
+        cls.unpack, cls.update, cls.unpack_from, cls.update_from, cls.iter_unpack, cls.iter_update = (
+            unpack.create_unpack_methods(cls)
+        )
+
+        return cls
+
+    return decorator(maybe_cls) if maybe_cls is not None else decorator

obstruct/methods.py

@@ -0,0 +1,49 @@
+import struct
+from collections.abc import Buffer
+from typing import Any, Sequence, Iterator, get_args, get_origin
+
+from typing_inspection.typing_objects import is_annotated
+
+from .struct_type import CType
+
+mapping = {
+    int: 'i', float: 'f', bool: '?'
+}
+
+CTypesFields = Sequence[str | CType | type] | Iterator[str | CType | type]
+
+
+def get_ctype(tp):
+    if isinstance(tp, str):
+        return tp
+    elif _ := getattr(tp, '__ctype__', None):
+        return _
+    elif _ := mapping.get(tp):
+        return _
+    elif is_annotated(get_origin(tp)):
+        # 目前需要 Annotated 的类型只有 array
+        tp_args = get_args(tp)
+        dtype = get_args(tp_args[0])[0]
+        length = tp_args[1]
+        c_size = struct.calcsize(get_ctype(dtype))
+        return f'{length * c_size}s'
+    else:
+        raise ValueError(f'Unrecognized type: {tp}')
+
+
+def to_format_string(fields: CTypesFields):
+    format = ''.join(
+        map(
+            get_ctype,
+            fields
+        )
+    )
+    return format
+
+
+def pack(format: CTypesFields, *data: Any) -> bytes:
+    return struct.pack(to_format_string(format), *data)
+
+
+def unpack(format: CTypesFields, data: Buffer):
+    return struct.unpack(to_format_string(format), data)

obstruct/struct_type.py

@@ -0,0 +1,52 @@
+import dataclasses
+import struct
+import typing
+from collections.abc import Buffer
+from typing import Self, Generator, Any, ClassVar
+
+
+class CType(typing.Protocol):
+    __ctype__: str
+
+
+class Struct(CType):
+    """
+    代表C语言结构体的Python类。
+    提供了将结构体对象与字节序列之间互相转换的功能，
+    包括打包、解包、更新等操作。
+    """
+
+    __cfields__: ClassVar[tuple[dataclasses.Field]]
+    __cstruct__: ClassVar[struct.Struct]
+    __cendian__: ClassVar[str]
+
+    def pack(self) -> bytes:
+        ...
+
+    def pack_into(self, buffer: Buffer, offset=0) -> None:
+        ...
+
+    @classmethod
+    def unpack(cls, buffer) -> Self:
+        ...
+
+    @classmethod
+    def unpack_from(cls, buffer, offset=0) -> Self:
+        ...
+
+    @classmethod
+    def iter_unpack(cls, buffer) -> Generator[Self, None, None]:
+        ...
+
+    @classmethod
+    def iter_update(cls, buffer) -> Generator[Self, None, None]:
+        ...
+
+    def update(self, buffer: Buffer) -> None:
+        ...
+
+    def update_from(self, buffer: Buffer, offset=0) -> None:
+        ...
+
+    def to_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)

obstruct/types/__init__.py

@@ -0,0 +1 @@
+from .types import *

obstruct/types/base.py

@@ -0,0 +1,6 @@
+def make_struct_type[T](name, pytype: type[T], ctype) -> type[T]:
+    return type(
+        name, (pytype,), {
+            '__ctype__': ctype
+        }
+    )

obstruct/types/types.py

@@ -0,0 +1,101 @@
+import builtins
+import sys
+from functools import lru_cache
+
+from .base import make_struct_type
+
+
+@lru_cache(maxsize=32)
+def pad(size: int):
+    return make_struct_type(
+        f'pad_{size}', builtins.bytes, f'{size}x'
+    )
+
+
+char = make_struct_type(
+    'char', builtins.bytes, 'c'
+)
+
+signed_char = make_struct_type(
+    'signed_char', builtins.int, 'b'
+)
+
+unsigned_char = make_struct_type(
+    'unsigned_char', builtins.int, 'B'
+)
+
+# bool = make_struct_type(
+#     'bool', builtins.int, '?'
+# )  # 布尔类型不能添加子类，也不允许添加新的类属性，只能特殊处理
+
+short = make_struct_type(
+    'short', builtins.int, 'h'
+)
+
+unsigned_short = make_struct_type(
+    'unsigned_short', builtins.int, 'H'
+)
+
+unsigned_int = make_struct_type(
+    'unsigned_int', builtins.int, 'I'
+)
+
+long = make_struct_type(
+    'long', builtins.int, 'l'
+)
+
+unsigned_long = make_struct_type(
+    'unsigned_long', builtins.int, 'L'
+)
+
+long_long = make_struct_type(
+    'long_long', builtins.int, 'q'
+)
+
+unsigned_long_long = make_struct_type(
+    'unsigned_long_long', builtins.int, 'Q'
+)
+
+double = make_struct_type(
+    'double', builtins.float, 'd'
+)
+
+short_float = make_struct_type(
+    'short_float', builtins.float, 'e'
+)
+
+size_t = make_struct_type(
+    'size_t', builtins.int, 'n'
+)
+
+ssize_t = make_struct_type(
+    'ssize_t', builtins.int, 'N'
+)
+
+
+# string (char[]), length must be specified when used
+@lru_cache(maxsize=32)
+def string(length):
+    return make_struct_type(f'string_{length}', builtins.bytes, f'{length}s')
+
+
+# pascal string (length-prefixed)
+@lru_cache(maxsize=32)
+def pascal_string(length):
+    return make_struct_type(f'pascal_string_{length}', builtins.bytes, f'{length}p')
+
+
+# pointer-sized integer (platform dependent)
+pointer = make_struct_type(
+    'pointer', builtins.int, 'P'
+)
+
+# >= 3.14
+if sys.version_info.major >= 3 and sys.version_info.minor >= 14:
+    float_complex = make_struct_type(
+        'complex', builtins.complex, 'F'
+    )
+
+    double_complex = make_struct_type(
+        'double_complex', builtins.complex, 'D'
+    )

obstruct/types/types.pyi

@@ -0,0 +1,67 @@
+import sys
+from typing import Literal, Sequence
+
+
+class _ctype:
+    __ctype__: str
+
+
+def pad(size: int) -> type: ...
+
+
+class char(bytes, _ctype): ...
+
+
+class signed_char(int, _ctype): ...
+
+
+class unsigned_char(int, _ctype): ...
+
+
+class long(int, _ctype): ...
+
+
+class unsigned_long(int, _ctype): ...
+
+
+class short(int, _ctype): ...
+
+
+class unsigned_short(int, _ctype): ...
+
+
+class unsigned_int(int, _ctype): ...
+
+
+class long_long(int, _ctype): ...
+
+
+class unsigned_long_long(int, _ctype): ...
+
+
+class double(float, _ctype): ...
+
+
+class short_float(float, _ctype): ...
+
+
+class size_t(int, _ctype): ...
+
+
+class ssize_t(int, _ctype): ...
+
+
+def string(length: int) -> type[bytes]: ...
+
+
+def pascal_string(length: int) -> type[bytes]: ...
+
+
+class pointer(int, _ctype): ...
+
+
+if sys.version_info >= (3, 14, 0):
+    class float_complex(complex, _ctype): ...
+
+
+    class double_complex(complex, _ctype): ...

obstruct-0.2.1.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.5
+Name: obstruct
+Version: 0.2.1
+Author-email: LittleNightSong <LittleNightSongYO@outlook.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.12

obstruct-0.2.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+obstruct/__init__.py,sha256=zM70fUvOP_Ne_9iAQQBRyST5GGag3yYNis4VAhQLWE4,121
+obstruct/__version__.py,sha256=S7TnOI7A9GMGYPhpcWZGb5luwiex3yTP5q-e9kmMZtw,19
+obstruct/decorator.py,sha256=D7KFh6tfLm-yAE1zhr5aqnyEVNPSOILM9hDguoUCYpI,1389
+obstruct/methods.py,sha256=UIUuvypBo7_SYPqQyknKootLqF-ggYGG39v5rZqvOzU,1278
+obstruct/struct_type.py,sha256=zxByrMqiKkH-i8VCpGM7jQdOyFzKo_edwrDq2RkNj2U,1233
+obstruct/aot/__init__.py,sha256=xj1UpN3cEyramzthzMILYwVWwkFmaAC2OiYxfDsKjk8,52
+obstruct/aot/aot.py,sha256=b1eOn14uy4OTMsjW7T8f-0Lk1vLsVd2dBPGNbWc253s,82
+obstruct/aot/base.py,sha256=L1UpXowWVLaIE3iChvyUdCP6lQx7XC2Qp62QeqziVL0,4115
+obstruct/aot/pack.py,sha256=IfSKYYA9n3n-ZTsnaxgcJFepDR_5rgKmKZO60k3-jVg,2550
+obstruct/aot/unpack.py,sha256=FHHVgJp4wkcnicEg7ZJ2KZ0GVxcSq94_xXgRN2wCRgU,5698
+obstruct/types/__init__.py,sha256=DGan05iQmXP3zYxpjkpv0DAClg41oBCF6WFZD1wSGDE,22
+obstruct/types/base.py,sha256=IZr2JIEtm5I3zxI5JcGM8X5_bZfTcxHyX8YfqPmNRMI,163
+obstruct/types/types.py,sha256=M9M7BCqQZswyHdxEXkOZtt2_lBv96HuicawrOH-o254,2167
+obstruct/types/types.pyi,sha256=p51EY4JjOVQ3HYUQvI0bZCmY9S5BFZO8JXQXCXnUh5A,966
+obstruct-0.2.1.dist-info/METADATA,sha256=U74R9PFbQ_sLLlRHPH_h6EgTt-zpLFgNMx7P80pHszI,519
+obstruct-0.2.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+obstruct-0.2.1.dist-info/RECORD,,

obstruct-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any