feat: add support for modifiers like offset specified through Annotated types

Author: MrIndeciso

libdestruct/common/struct/struct_impl.py

@@ -6,6 +6,8 @@
 
 from __future__ import annotations
 
+from typing import Annotated, get_args, get_origin
+
 from typing_extensions import Self
 
 from libdestruct.backing.fake_resolver import FakeResolver
@@ -131,8 +133,17 @@ def _resolve_field(
             Either resolved_inflater or bitfield_field will be non-None (not both).
             explicit_offset is set when an OffsetAttribute is present.
         """
+        # Unwrap Annotated[type, metadata...] — extract the real type and any metadata
+        annotated_offset = None
+        if get_origin(annotation) is Annotated:
+            ann_args = get_args(annotation)
+            annotation = ann_args[0]
+            for meta in ann_args[1:]:
+                if isinstance(meta, OffsetAttribute):
+                    annotated_offset = meta.offset
+
         if name not in reference.__dict__:
-            return inflater.inflater_for(annotation, owner=owner), None, None
+            return inflater.inflater_for(annotation, owner=owner), None, annotated_offset
 
         attrs = getattr(reference, name)
         if not isinstance(attrs, tuple):
@@ -143,7 +154,7 @@ def _resolve_field(
 
         resolved_type = None
         bitfield_field = None
-        explicit_offset = None
+        explicit_offset = annotated_offset
 
         for attr in attrs:
             if isinstance(attr, BitfieldField):

test/scripts/struct_unit_test.py

@@ -7,7 +7,9 @@
 import unittest
 from enum import IntEnum
 
-from libdestruct import array, c_int, c_long, c_short, c_uint, inflater, struct, ptr, ptr_to_self, array_of, enum, enum_of
+from typing import Annotated
+
+from libdestruct import array, c_int, c_long, c_short, c_uint, inflater, offset, struct, ptr, ptr_to_self, array_of, enum, enum_of
 
 
 class StructMemberCollisionTest(unittest.TestCase):
@@ -354,6 +356,59 @@ class s_t(struct):
         self.assertEqual(s.coords[1].value, 20)
 
 
+class AnnotatedOffsetTest(unittest.TestCase):
+    """Test Annotated[type, offset(N)] syntax for explicit field offsets."""
+
+    def test_annotated_offset_basic(self):
+        """Annotated[c_int, offset(N)] places a field at the given offset."""
+        class s_t(struct):
+            a: c_int
+            b: Annotated[c_int, offset(8)]
+
+        from libdestruct import size_of
+        self.assertEqual(size_of(s_t), 12)  # 8 + 4
+
+    def test_annotated_offset_read(self):
+        """Values are read correctly from Annotated offset positions."""
+        import struct as pystruct
+
+        class s_t(struct):
+            a: c_int
+            b: Annotated[c_int, offset(8)]
+
+        memory = pystruct.pack("<i", 10) + b"\x00" * 4 + pystruct.pack("<i", 20)
+        s = s_t.from_bytes(memory)
+        self.assertEqual(s.a.value, 10)
+        self.assertEqual(s.b.value, 20)
+
+    def test_annotated_offset_with_subscript(self):
+        """Annotated works with subscript syntax types."""
+        class s_t(struct):
+            a: c_int
+            data: Annotated[array[c_int, 2], offset(8)]
+
+        from libdestruct import size_of
+        self.assertEqual(size_of(s_t), 16)  # 8 + 2*4
+
+    def test_annotated_offset_with_ptr(self):
+        """Annotated works with ptr subscript syntax."""
+        class s_t(struct):
+            a: c_int
+            ref: Annotated[ptr[c_int], offset(8)]
+
+        from libdestruct import size_of
+        self.assertEqual(size_of(s_t), 16)  # 8 + 8
+
+    def test_old_offset_syntax_still_works(self):
+        """The old offset() default value syntax continues to work."""
+        class s_t(struct):
+            a: c_int
+            b: c_int = offset(8)
+
+        from libdestruct import size_of
+        self.assertEqual(size_of(s_t), 12)
+
+
 class StructEqualityTest(unittest.TestCase):
     def test_struct_eq_non_struct_returns_not_implemented(self):
         """struct.__eq__ returns NotImplemented for non-struct values."""