Merge pull request #2 from xpodev/use-metaclass

Use metaclass

Author: binyamin555

README.md

@@ -56,6 +56,56 @@ When deserializing a struct with multiple bases or if one of the fields was over
 the deserialization must be done through the exact type of the struct.
 
 
+# Fixed Size Structs
+A fixed size struct is any struct that has a known fixed time that doesn't depend on the 
+data it holds. QuickStruct can verify a struct has a fixed size.
+```py
+# The StructFlags.FixedSize flag is used to verify the struct has a fixed size.
+# If the size could not be verified, a SizeError is raised.
+class FixedSizeStruct(DataStruct, flags=StructFlags.FixedSize):
+    a: i32
+    b: i8
+    c: f32
+    d: char
+    e: String[10] # 10 character string
+    f: Person[3] # 3 'person' objects
+    # g: Array[i32] <- not a fixed size field. this will error
+```
+
+# Struct Properties
+It is possible to query some information about a structure.
+```py
+from quickstruct import *
+class Fixed(DataStruct):
+    s: String[10]
+    x: i32
+
+class Dynamic(DataStruct):
+    s: String
+    x: i32
+
+print("Fixed.size:", Fixed.size) # 16 (padding automatically added)
+print("Dynamic.size:", Dynamic.size) # -1 (dynamic size)
+
+print("Fixed.is_fixed_size:", Fixed.is_fixed_size) # True
+print("Dynamic.is_fixed_size:", Fixed.is_fixed_size) # False
+
+print("Fixed.is_dynamic_size:", Fixed.is_dynamic_size) # False
+print("Dynamic.is_dynamic_size:", Fixed.is_dynamic_size) # True
+
+print("Fixed.fields:", Fixed.fields) # [s: String[10], __pad_0__: Padding(2), x: i32]
+print("Dynamic.fields:", Dynamic.fields) # [s: String, x: i32]
+
+print("Fixed.aligment:", Fixed.aligment) # 16.
+print("Dynamic.aligment:", Dynamic.aligment) # -1 (no alignment because dynamic struct can't be aligned).
+
+print("Fixed.is_final:", Fixed.is_final) # False
+print("Dynamic.is_final:", Fixed.is_final) # False
+
+print("Fixed.is_protected:", Fixed.is_protected) # False
+print("Dynamic.is_protected:", Fixed.is_protected) # False
+```
+
 # Alignment
 It is also possible to add padding to the struct. There are 2 ways to do that:
 ## Manual Alignment
@@ -82,22 +132,24 @@ class AlignedStruct(DataStruct, flags = StructFlags.Align2Bytes):
 ```
 
 ## Struct Flags
-| Flag              | Description                                                                                                           |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------|
-| NoAlignment       | This is the most packed form of the struct. All fields are adjacent with no padding (unless manually added)           |
-| Packed            | Same as `NoAlignment` except that `NoAlignment` is a bit more optimized because no alignment is done.                 |
-| Align1Byte        | Same as `Packed`                                                                                                      |
-| Align2Bytes       | Aligns the fields on 2 byte boundary.                                                                                 |
-| Align4Bytes       | Aligns the fields on 4 byte boundary.                                                                                 |
-| Align8Bytes       | Aligns the fields on 8 byte boundary.                                                                                 |
-| AlignAuto         | Aligns the fields by their type.                                                                                      |
-| ReorderFields     | Specifies the fields should be reordered in order to make the struct a little more compressed.                        |
-| ForceDataOnly     | Specifies that the struct may only contain serializable fields. Data-only structs may only inherit data-only structs. |
-| AllowOverride     | If set, fields defined in the struct may override fields that are defined in the base struct.                         |
-| ForceSafeOverride | If set, when fields are overridden, they must have the same type (which would make it pretty useless to override).    |
-| ForceFixedSize    | If set, the struct must have a fixed size. If not, an exception is raised.                                            |
-| AllowInline       | If set, the struct's fields will be inlined into another struct the contains this struct.                             |
-| Final             | Marks the structure so it won't be inheritable by any other class.                                                    |
-| LockedStructure   | If set, denies any overrides of that structure. This flag is not yet implemented.                                     |
-
-
+| Flag              | Description                                                                                                                                                                                                      |
+|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Default           | The default to use if no flags are given. Same as `AllowOverride \| AlignAuto`.                                                                                                                                  |
+| NoAlignment       | This is the most packed form of the struct. All fields are adjacent with no padding (unless manually added)                                                                                                      |
+| Packed            | Same as `NoAlignment` except that `NoAlignment` is a bit more optimized because no alignment is done.                                                                                                            |
+| Align1Byte        | Same as `Packed`                                                                                                                                                                                                 |
+| Align2Bytes       | Aligns the fields on 2 byte boundary.                                                                                                                                                                            |
+| Align4Bytes       | Aligns the fields on 4 byte boundary.                                                                                                                                                                            |
+| Align8Bytes       | Aligns the fields on 8 byte boundary.                                                                                                                                                                            |
+| AlignAuto         | Aligns the fields by their type.                                                                                                                                                                                 |
+| ReorderFields     | Specifies the fields should be reordered in order to make the struct a little more compressed.                                                                                                                   |
+| ForceDataOnly     | **Deprecated**. Specifies that the struct may only contain serializable fields. Data-only structs may only inherit data-only structs.                                                                            |
+| AllowOverride     | If set, fields defined in the struct may override fields that are defined in the base struct.                                                                                                                    |
+| TypeSafeOverride  | If set, when fields are overridden, they must have the same type (which would make it pretty useless to override). Implies `AllowOverride`. If fields have a different type, an `UnsafeOverrideError` is raised. |
+| ForceSafeOverride | **Deprectaed**. Same as `TypeSafeOverride`.                                                                                                                                                                      |
+| FixedSize         | If set, the struct must have a fixed size. If not, an exception `SizeError` is raised.                                                                                                                           |
+| ForceFixedSize    | **Deprecated**. Same as `FixedSize`.                                                                                                                                                                             |
+| AllowInline       | **Deprecated**. If set, the struct's fields will be inlined into another struct the contains this struct.                                                                                                        |
+| Protected         | If set, denies any overrides of that structure. If a struct is trying to override a field of it, an `UnoverridableFieldError` is raised.                                                                         |
+| LockedStructure   | **Deprecated**. Same as `Protected`.                                                                                                                                                                             |
+| Final             | Marks the structure so it won't be inheritable by any other class. If a struct is trying to inherit it, an `InheritanceError` is raised.                                                                         |

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "quickstruct"
-version = "0.1.4"
+version = "0.2.0"
 description = "A small library to ease the creation, usage, serialization and deserialization of C structs."
 authors = ["Binyamin Y Cohen <binyamincohen555@gmail.com>"]
 repository = "https://github.com/xpodev/quickstruct"

quickstruct/__init__.py

@@ -2,7 +2,7 @@
 from .quickstruct import *
 from .struct_builder import StructFlags
 
-__version__ = '0.1.4'
+__version__ = '0.2.0'
 
 
 __all__ = [
@@ -12,6 +12,8 @@
     'DataStruct',
 
     'String',
+    'Array',
+
     'i8',
     'i16',
     'i32',
@@ -26,5 +28,7 @@
 
     'ptr',
     'ref',
-    'anyptr'
+    'anyptr',
+
+    'Padding'
 ]

quickstruct/common.py

@@ -17,32 +17,44 @@ def __repr__(self) -> str:
     def __instancecheck__(cls, value) -> bool:
         return cls.__is_instance__(value)
 
+    @property
+    def is_dynamic_size(self) -> bool:
+        return self._is_dynamic_size()
+
+    @property
+    def alignment(self) -> int:
+        return self._alignment()
+
+    @property
+    def size(self) -> int:
+        return self._size()
+
 
 class Type(typing.Generic[U], metaclass=TypeMeta):   
     def __class_getitem__(cls: typing.Type[U], item) -> "typing.Type[Array[U]]":
         if isinstance(item, int):
             if issubclass(cls, Padding):
-                return type(f"Padding({item})", (cls,), {
+                return type(f"Padding[{item}]", (cls,), {
                     "__struct__": Struct(f"{item}x"),
                 })
             return _array(cls, item)
         return super().__class_getitem__(item)
 
     @classmethod
-    def is_dynamic_size(cls) -> bool:
-        return cls.size() == -1
+    def _is_dynamic_size(cls) -> bool:
+        return cls.size == -1
 
     @classmethod
-    @abstractmethod
-    def alignment(cls) -> int:
+    # @abstractmethod
+    def _alignment(cls) -> int:
         """Returns the alignment of the type."""
-        pass
+        raise NotImplementedError
 
     @classmethod
-    @abstractmethod
-    def size(cls) -> int:
+    # @abstractmethod
+    def _size(cls) -> int:
         """The size of the type in bytes. If the type doesn't have a fixed size, -1 is returned."""
-        raise NotImplementedError()
+        raise NotImplementedError
 
     @classmethod
     @abstractmethod
@@ -60,6 +72,7 @@ def __is_instance__(cls, instance) -> bool:
         """Checks if the given instance is an instance of this type."""
         return type.__instancecheck__(cls, instance)
 
+
 T = typing.TypeVar('T', covariant=True, bound=Type)
 
 
@@ -69,11 +82,11 @@ class Primitive(Type, typing.Generic[T]):
     __alignment__: int
 
     @classmethod
-    def size(cls) -> int:
+    def _size(cls) -> int:
         return cls.__struct__.size
 
     @classmethod
-    def alignment(cls) -> int:
+    def _alignment(cls) -> int:
         return cls.__alignment__
 
     @classmethod
@@ -106,19 +119,19 @@ def to_bytes(cls, _) -> bytes:
     def from_bytes(cls, data: typing.Union[bytes, BytesIO]) -> T:
         if isinstance(data, bytes):
             data = BytesIO(data)
-        return cls.__struct__.unpack(data.read(cls.__struct__.size))[0]
+        cls.__struct__.unpack(data.read(cls.__struct__.size))
 
 
 class String(Type):
     __length__: int = None
     __alignment__: int = 1
 
     @classmethod
-    def size(cls) -> int:
+    def _size(cls) -> int:
         return cls.__length__ if cls.__length__ else -1
 
     @classmethod
-    def alignment(cls) -> int:
+    def _alignment(cls) -> int:
         return cls.__alignment__
 
     @classmethod
@@ -156,16 +169,16 @@ def __class_str__(cls) -> str:
 
 
 class Array(Type, typing.Generic[T]):
-    __element_type__: T
+    __element_type__: typing.Type[T]
     __length__: int = None
 
     @classmethod
-    def size(cls) -> int:
-        return cls.__length__ if cls.__length__ else -1
+    def _size(cls) -> int:
+        return cls.__length__ * cls.__element_type__.size if cls.__length__ else -1
 
     @classmethod
-    def alignment(cls) -> int:
-        return cls.__element_type__.alignment()
+    def _alignment(cls) -> int:
+        return cls.__element_type__.alignment
 
     @classmethod
     def to_bytes(cls, values: typing.Iterable[T]) -> bytes:
@@ -286,8 +299,7 @@ def __getitem__(self, item):
 
 
 __all__ = [
-    "Type", "Primitive", "String", "Array", "Pointer", "Reference",
+    "Type", "Primitive", "String", "Array", "Pointer", "Reference", "Padding", "Array",
     "i8", "u8", "i16", "u16", "i32", "u32", "i64", "u64", "f32", "f64", "anyptr", "char",
-    "ptr", "ref",
-    "T"
+    "ptr", "ref"
 ]

quickstruct/error.py

@@ -0,0 +1,33 @@
+class QuickStructError(Exception):
+    """Base class for all QuickStruct errors."""
+    pass
+
+
+class FieldError(QuickStructError):
+    """Base class for all field errors."""
+    pass
+
+
+class OverrideError(FieldError):
+    """Raised when a field is override is not allowed."""
+    pass
+
+
+class UnoverridbaleFieldError(FieldError):
+    """Raised when a field is overriding a locked field."""
+    pass
+
+
+class UnsafeOverrideError(FieldError):
+    """Raised when a field is overriding a field with a different type when the struct is marked as SafeOverride."""
+    pass
+
+
+class InheritanceError(QuickStructError):
+    """Raised when an invalid inheritance is detected."""
+    pass
+
+
+class SizeError(QuickStructError):
+    """Raised when an invalid size is detected."""
+    pass

quickstruct/field.py

@@ -0,0 +1,96 @@
+from enum import IntFlag
+import typing
+
+from .common import Type
+
+
+class FieldFlags(IntFlag):
+    NONE = 0
+    """No flags set."""
+    Protected = 1 << 0
+    """If set, the field can't be overridden by a derived struct."""
+
+
+class StructField:
+    _type: typing.Type[Type]
+    _name: str
+
+    def __init__(self, typ: typing.Type[Type]) -> None:
+        self._type = typ
+
+    def __set_name__(self, _, name):
+        self._name = f"__field_{name}__"
+
+    def __get__(self, instance, _):
+        if instance is None:
+            return self
+        return getattr(instance, self._name)
+
+    def __set__(self, instance, value):
+        if not isinstance(value, self._type):
+            raise TypeError(f"Expected {self._type}, got {type(value)}")
+        setattr(instance, self._name, value)
+
+
+class StructPaddingField:
+    _name: str
+
+    def __set_name__(self, _, name):
+        self._name = f"__field_{name}__"
+
+    def __get__(self, instance, _):
+        if instance is None:
+            return self
+        return None
+
+
+class FieldInfo:
+    _name: str
+    _type: Type
+    _offset: int
+    _flags: FieldFlags
+
+    def __init__(self, name: str, typ: Type, flags: FieldFlags = FieldFlags.NONE) -> None:
+        if name is None:
+            raise TypeError("Field name must not be None")
+        if typ is None:
+            raise TypeError("Field type must not be None")
+        self._name = name
+        self._type = typ
+        self._offset = 0
+        self._flags = flags
+
+    @property
+    def name(self) -> str:
+        return self._name
+    
+    @property
+    def type(self) -> Type:
+        return self._type
+
+    @type.setter
+    def type(self, typ: Type) -> None:
+        self._type = typ
+
+    @property
+    def offset(self) -> int:
+        return self._offset
+
+    @offset.setter
+    def offset(self, value: int) -> None:
+        self._offset = value
+
+    @property
+    def flags(self) -> FieldFlags:
+        return self._flags
+
+    @flags.setter
+    def flags(self, value: FieldFlags) -> None:
+        self._flags = value
+
+    @property
+    def is_protected(self) -> bool:
+        return self._flags & FieldFlags.Protected
+
+    def __repr__(self) -> str:
+        return f"{self._name}: {self._type}"