Sync main with dev branch by MrIndeciso · Pull Request #7 · libdebug/libdestruct

MrIndeciso · 2026-04-01T14:09:52Z

Fixes #1.
Fixes #2.
Fixes #5.
Fixes #6.

…irectly

…fixed itself

This propagates down the chain, and everything works big-endian

…arrays

…ed types

Copilot

Pull request overview

Syncs main with dev, bringing in major core-library features (endianness, alignment, unions/bitfields, forward refs, hexdump, dict export) plus a large set of new tests and docs.

Changes:

Add endianness support across inflater/resolvers and primitive types (incl. float/double).
Implement/extend core type features: struct alignment + explicit offsets, unions (plain/tagged), bitfields, pointer arithmetic + caching, hexdump/to_dict, and forward-reference pointer syntax.
Add extensive pytest/unittest coverage and introduce MkDocs documentation structure/config.

Reviewed changes

Copilot reviewed 74 out of 74 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
test/scripts/types_unit_test.py	Adds unit tests for primitives, ptr behavior, floats, c_str, hexdump, comparisons
test/scripts/to_dict_test.py	Adds `to_dict()` behavior tests (primitive/struct/array/union/enum)
test/scripts/tagged_union_test.py	Adds tests for tagged/plain unions and freeze/diff/reset
test/scripts/struct_unit_test.py	Adds tests for struct collisions, freeze semantics, forward refs, equality
test/scripts/struct_parser_unit_test.py	Adds tests for C parser pointers/arrays/typedefs inflation
test/scripts/resolver_unit_test.py	Adds tests for FakeResolver/MemoryResolver bytes behavior and writes
test/scripts/enum_test.py	Extends enum tests (to_str formatting, bytes behavior, value extraction)
test/scripts/endianness_test.py	Adds endianness test suite (ints/floats/structs/ptrs/arrays/bitfields)
test/scripts/bitfield_unit_test.py	Adds bitfield tests (packing, signed, parser support, freeze)
test/scripts/basic_struct_test.py	Adds forward-ref ptr syntax test in existing suite
test/scripts/array_unit_test.py	Adds array unit tests (value/get, iteration, to_bytes/to_dict)
test/scripts/alignment_test.py	Adds struct alignment/offset/array/bitfield alignment tests
SKILL.md	Adds/updates skills-style reference documentation
README.md	Expands README with installation + quick-start examples
pyproject.toml	Updates Ruff ignore list (adds COM812)
mkdocs.yml	Adds MkDocs Material configuration + navigation
libdestruct/libdestruct.py	Adds endianness parameter to `inflater()`/`inflate()`
libdestruct/common/utils.py	Expands `size_of()`, adds `alignment_of()`, and resolves string annotations
libdestruct/common/union/union.py	Introduces union runtime type (plain/tagged) with freeze/diff/to_bytes
libdestruct/common/union/union_of.py	Adds `union_of()` field factory
libdestruct/common/union/union_field.py	Adds `UnionField` descriptor and size computation
libdestruct/common/union/union_field_inflater.py	Registers union field inflater (inflate all variants)
libdestruct/common/union/tagged_union_of.py	Adds `tagged_union()` field factory
libdestruct/common/union/tagged_union_field.py	Adds `TaggedUnionField` descriptor and size computation
libdestruct/common/union/tagged_union_field_inflater.py	Inflates tagged union variant based on discriminator member
libdestruct/common/union/init.py	Exposes union APIs and registers inflaters
libdestruct/common/type_registry.py	Adds support for subscripted generics via generic handlers
libdestruct/common/struct/struct.py	Adds endianness to `struct.from_bytes()` and freezes result
libdestruct/common/struct/struct_impl.py	Adds member-collision handling, alignment, padding-aware `to_bytes`, `to_dict`, `hexdump`, eq semantics
libdestruct/common/struct/init.py	Reorders `__all__` exports
libdestruct/common/ptr/ptr.py	Adds pointer caching, arithmetic, indexing; supports endianness via Resolver
libdestruct/common/obj.py	Adds generic typing, endianness propagation, comparisons, `to_dict()`, `hexdump()`, endianness-aware from_bytes
libdestruct/common/inflater.py	Adds endianness plumbing into MemoryResolver creation
libdestruct/common/hexdump.py	Adds hexdump formatter utility
libdestruct/common/forward_ref_inflater.py	Adds lazy forward-ref ptr inflater + generic ptr[T] handling
libdestruct/common/enum/enum.py	Fixes enum `to_str()` indentation behavior
libdestruct/common/bitfield/bitfield.py	Adds bitfield runtime type with packing + signed extraction
libdestruct/common/bitfield/bitfield_tracker.py	Adds struct inflation helper for grouping bitfields
libdestruct/common/bitfield/bitfield_of.py	Adds `bitfield_of()` factory with validation
libdestruct/common/bitfield/bitfield_field.py	Adds BitfieldField descriptor
libdestruct/common/bitfield/init.py	Exposes bitfield APIs
libdestruct/common/array/array.py	Updates array `get()` signature to allow “all elements” default
libdestruct/common/array/array_impl.py	Implements `get(-1)` and adds array `to_dict()`
libdestruct/common/init.py	Ensures forward-ref inflater registration on import
libdestruct/c/struct_parser.py	Adds bitfield parsing, nested pointer typedef support, native float/double mapping, cache clearing
libdestruct/c/ctypes_generic.py	Fixes frozen to_bytes behavior for ctypes generics
libdestruct/c/c_str.py	Fixes get index logic, adds `__setitem__`
libdestruct/c/c_float_types.py	Adds native float/double implementations with endianness
libdestruct/c/base_type_inflater.py	Registers float/double types in type registry
libdestruct/c/init.py	Exposes float/double types
libdestruct/backing/resolver.py	Adds endianness attribute to Resolver base
libdestruct/backing/memory_resolver.py	Adds endianness propagation + ensures resolve returns bytes
libdestruct/backing/fake_resolver.py	Adds endianness propagation + adjusts default page reads
libdestruct/init.py	Exposes new APIs (endianness helpers, unions, bitfields, alignment_of, more C types)
docs/memory/resolvers.md	Adds resolver documentation
docs/memory/inflater.md	Adds inflater documentation
docs/index.md	Adds docs landing page
docs/basics/types.md	Adds primitive types documentation
docs/basics/structs.md	Adds struct documentation
docs/basics/pointers.md	Adds pointer documentation
docs/basics/getting_started.md	Adds getting started guide
docs/basics/enums.md	Adds enum documentation
docs/basics/arrays.md	Adds array documentation
docs/advanced/tagged_unions.md	Adds union documentation
docs/advanced/offset.md	Adds explicit offset documentation
docs/advanced/hexdump.md	Adds hexdump documentation
docs/advanced/freeze_diff.md	Adds freeze/diff/reset documentation
docs/advanced/forward_refs.md	Adds forward reference documentation
docs/advanced/c_parser.md	Adds C parser documentation
docs/advanced/bitfields.md	Adds bitfield documentation
docs/advanced/alignment.md	Adds alignment documentation
.github/workflows/test.yml	Expands CI Python version matrix

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-01T14:15:21Z

libdestruct/common/ptr/ptr.py

    def unwrap(self: ptr, length: int | None = None) -> obj:
        """Return the object pointed to by the pointer.

        Args:
            length: The length of the object in memory this points to.
        """
+        if self._cache_valid:
+            return self._cached_unwrap
+
        address = self.get()

        if self.wrapper:
            if length:
                raise ValueError("Length is not supported when unwrapping a pointer to a wrapper object.")

-            return self.wrapper(self.resolver.absolute_from_own(address))
-
-        if not length:
-            length = 1
+            result = self.wrapper(self.resolver.absolute_from_own(address))
+        else:
+            target_resolver = self.resolver.absolute_from_own(address)
+            result = target_resolver.resolve(length or 1, 0)

-        return self.resolver.resolve(length, 0)
+        self._cached_unwrap = result
+        self._cache_valid = True
+        return result


ptr.unwrap()/try_unwrap() caching ignores the length parameter for untyped pointers. If a caller unwraps the same pointer with different lengths, the cached value can return an incorrectly-sized byte string. Consider keying the cache by length (and wrapper), or disabling caching when wrapper is None and length is provided.

Copilot · 2026-04-01T14:15:21Z

libdestruct/common/ptr/ptr.py

    def unwrap(self: ptr, length: int | None = None) -> obj:
        """Return the object pointed to by the pointer.

        Args:
            length: The length of the object in memory this points to.
        """
+        if self._cache_valid:
+            return self._cached_unwrap
+
        address = self.get()

        if self.wrapper:
            if length:
                raise ValueError("Length is not supported when unwrapping a pointer to a wrapper object.")

-            return self.wrapper(self.resolver.absolute_from_own(address))
-
-        if not length:
-            length = 1
+            result = self.wrapper(self.resolver.absolute_from_own(address))
+        else:
+            target_resolver = self.resolver.absolute_from_own(address)
+            result = target_resolver.resolve(length or 1, 0)

-        return self.resolver.resolve(length, 0)
+        self._cached_unwrap = result
+        self._cache_valid = True
+        return result


ptr.unwrap() is annotated to return obj, but in the untyped case it returns bytes and stores that into _cached_unwrap (typed as obj | None). This breaks type expectations for callers and static typing. Consider widening the return type to obj | bytes (and the cache type accordingly), or always wrap raw bytes in an obj type.

Copilot · 2026-04-01T14:15:21Z

libdestruct/libdestruct.py

+def inflater(memory: Sequence, endianness: str = "little") -> Inflater:
    """Return a TypeInflater instance."""
    if not isinstance(memory, Sequence):
        raise TypeError(f"memory must be a MutableSequence, not {type(memory).__name__}")

-    return Inflater(memory)
+    return Inflater(memory, endianness=endianness)


The error message says "memory must be a MutableSequence" but the check accepts any Sequence. Either validate MutableSequence (if mutability is required) or update the error message/type hints to match the actual accepted types (e.g., Sequence[SupportsBytes]).

Copilot · 2026-04-01T14:15:22Z

docs/memory/resolvers.md

+All resolvers implement these methods:
+
+| Method | Description |
+|---|---|
+| `resolve(size, offset)` | Read `size` bytes starting at the resolved address + offset |
+| `resolve_address()` | Return the absolute address of this resolver |
+| `write(data)` | Write bytes at the resolved address |
+| `relative_from_own(offset, size)` | Create a child resolver at a relative offset |
+| `absolute_from_own(address)` | Create a child resolver at an absolute address |
+
+## Custom Memory Backends
+
+If you need to read from a custom source (e.g., a debugger's memory API, a remote process, a file), you can subclass `Resolver`:
+
+```python
+from libdestruct.backing.resolver import Resolver
+
+class DebuggerResolver(Resolver):
+    def __init__(self, debugger, address):
+        self.debugger = debugger
+        self._address = address
+
+    def resolve(self, size, offset=0):
+        return self.debugger.read_memory(self._address + offset, size)
+
+    def resolve_address(self):
+        return self._address
+
+    def write(self, data, offset=0):
+        self.debugger.write_memory(self._address + offset, data)
+
+    # ... implement relative_from_own, absolute_from_own


docs/memory/resolvers.md describes a write() method and shows an example implementation, but the Resolver interface defines modify(size, index, value) instead. Please update the docs (method table + example) to match the actual Resolver API, including the index/offset parameter conventions.

Copilot · 2026-04-01T14:15:22Z

docs/basics/enums.md

+# Subscript syntax (preferred)
+class pixel_t(struct):
+    color: enum[Color]        # defaults to c_int backing type
+    x: c_int
+    y: c_int
+
+# With a custom backing type:
+class pixel2_t(struct):


This example uses enum_of(Color, c_int) and color: enum_of(...), but enum_of actually takes (enum_type, lenient=True, size=4) and the field is typically annotated as enum with enum_of(Color) as the default value (see libdestruct/common/enum/enum_of.py). Update the snippet to reflect the real API so it is valid Python and matches behavior.

Copilot · 2026-04-01T14:15:22Z

docs/basics/pointers.md

+```python
+from libdestruct import struct, c_int, ptr, inflater
+
+class data_t(struct):
+    value: c_int
+    next: ptr[c_int]
+```
+


The pointer field example uses next: ptr_to(c_int) as a type annotation, but ptr_to() returns a field descriptor that should be used as the default value (e.g., next: ptr = ptr_to(c_int)). As written, the snippet is not valid/idiomatic for this library’s API.

Copilot · 2026-04-01T14:15:22Z

docs/basics/pointers.md

+import struct as pystruct
+memory[0:4] = pystruct.pack("<i", 42)
+memory[4:12] = pystruct.pack("<q", 12)      # next -> offset 12
+memory[12:16] = pystruct.pack("<i", 99)     # value at offset 12
+
+data = lib.inflate(data_t, 0)
+print(data.value.value)           # 42
+print(data.next.unwrap().value)   # 99
+```
+
+### Safe Dereferencing
+
+Use `try_unwrap()` for null-safe pointer access. It returns `None` if the pointer is null (0):
+
+```python


The try_unwrap() section states it returns None when the pointer is null (0), but the implementation only checks whether the address is resolvable; address 0 can be valid in a buffer-backed resolver. Consider rewording this to “returns None if the address is invalid/unresolvable” (or implement explicit null-pointer semantics if that’s desired).

Copilot · 2026-04-01T14:15:23Z

docs/basics/types.md

+s = lib.inflate(c_str, 0)
+print(s.value)  # "Hello"
+print(len(s))   # 5


This c_str example implies .value is a Python string and s[0] returns an int (72), but c_str.get()/__getitem__ return bytes (e.g., b"H") and .value returns bytes as well. Please update the example outputs/types to match the actual behavior.

Suggested change

s = lib.inflate(c_str, 0)

print(s.value) # "Hello"

print(len(s)) # 5

print(s.value) # b"Hello"

print(len(s)) # 5

print(s[0]) # b"H"

Copilot

Pull request overview

Copilot reviewed 77 out of 77 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-01T17:39:09Z

libdestruct/common/utils.py

 def size_of(item_or_inflater: obj | callable[[Resolver], obj]) -> int:
-    """Return the size of an object, from an obj or it's inflater."""
-    if hasattr(item_or_inflater.__class__, "size"):
-        # This has the priority over the size of the object itself
-        # as we might be dealing with a struct object
-        # that defines an attribute named "size"
+    """Return the size in bytes of a type, instance, or field descriptor."""
+    # Field instances (e.g. array_of, ptr_to) — must come before .size check
+    if isinstance(item_or_inflater, Field):
+        return item_or_inflater.get_size()
+    if is_field_bound_method(item_or_inflater):
+        return item_or_inflater.__self__.get_size()
+


size_of() currently doesn’t handle subscripted “generic” types produced by the new API (e.g. array[c_int, 10], enum[Color], ptr[T]). Those expressions create a GenericAlias/typing object rather than a class/Field, so size_of(array[c_int, 10]) raises ValueError, contradicting the new documentation and making direct size queries for these types fail. Consider detecting typing.get_origin()/get_args() (or types.GenericAlias) here and routing through TypeRegistry().inflater_for(...) to obtain a Field-bound inflater whose size can be computed, so size_of works for both legacy factories and subscript syntax.

Copilot · 2026-04-01T17:39:09Z

libdestruct/common/union/union.py

+    def reset(self: union) -> None:
+        """Reset the union to its frozen value."""
+        if self._variant is not None:
+            self._variant.reset()
+        else:
+            for v in self._variants.values():
+                v.reset()


union.reset() does not restore the frozen union-wide byte region captured in freeze(). For tagged unions this means padding bytes (outside the active variant) won’t be reset; for plain unions, iterating over variants and resetting each can write overlapping memory multiple times and can yield incorrect final bytes depending on variant sizes/order. A safer approach is to, when frozen and resolver is present, write back _frozen_bytes for the full union size (and optionally then reset the active variant view).

Copilot · 2026-04-01T17:39:10Z

libdestruct/common/struct/struct_impl.py

+    def hexdump(self: struct_impl) -> str:
+        """Return a hex dump of this struct's bytes with field annotations."""
+        member_offsets = object.__getattribute__(self, "_member_offsets")
+        members = object.__getattribute__(self, "_members")
+        annotations = {member_offsets[name]: name for name in members}
+        address = struct_impl.address.fget(self) if not object.__getattribute__(self, "_frozen") else 0
+        return format_hexdump(self.to_bytes(), address, annotations)


struct_impl.hexdump() builds annotations as a dict keyed by byte offset, so if multiple members share the same offset (e.g., consecutive bitfields in the same backing integer), earlier names are overwritten and the hexdump will only show one of them. Consider storing a list of names per offset (or emitting group-owner-only offsets) and adapting format_hexdump to display all field names that start at a given offset.

Copilot · 2026-04-01T17:39:10Z

docs/basics/enums.md

+class pixel_t(struct):
+    color: enum_of(Color, c_int)


This legacy example is incorrect: enum_of()’s second parameter is lenient (bool), not a backing type. Passing c_int here will be treated as truthy and won’t set the backing size/type. The example should either use the preferred enum[Color] / enum[Color, c_short] syntax, or use enum_of(Color, size=4) (and document how to select alternate backing sizes/types).

Suggested change

class pixel_t(struct):

color: enum_of(Color, c_int)

# Legacy factory syntax. Use the size (in bytes) to select the backing type.

# For example, size=2 => 16-bit backing; size=4 => 32-bit backing.

class pixel_t(struct):

color: enum_of(Color, size=4)

Copilot · 2026-04-01T17:39:10Z

docs/advanced/forward_refs.md

+from libdestruct import struct, c_int, ptr_to_self
+
+class Node(struct):
+    val: c_int
+    next: ptr_to_self


This legacy ptr_to_self example is invalid usage: ptr_to_self is a factory function that must be called and assigned as a field default (e.g., next: ptr = ptr_to_self()), not used as a bare annotation. As written it won’t create a pointer field descriptor and won’t behave like ptr["Node"].

Suggested change

from libdestruct import struct, c_int, ptr_to_self

class Node(struct):

val: c_int

next: ptr_to_self

from libdestruct import struct, c_int, ptr, ptr_to_self

class Node(struct):

val: c_int

next: ptr = ptr_to_self()

Copilot · 2026-04-01T17:39:11Z

docs/basics/types.md

+size_of(array[c_int, 10])     # 40
+size_of(array_of(c_int, 10))  # 40 (legacy syntax)


The documentation claims size_of(array[c_int, 10]) works, but size_of() currently does not handle subscripted GenericAlias types (it raises ValueError). Either update size_of() to support the subscript syntax types directly, or adjust this example to use array_of(c_int, 10) until support is added.

Suggested change

size_of(array[c_int, 10]) # 40

size_of(array_of(c_int, 10)) # 40 (legacy syntax)

size_of(array_of(c_int, 10)) # 40

Copilot · 2026-04-01T17:39:11Z

test/scripts/to_dict_test.py

+    def test_struct_with_ptr_to_dict(self):
+        """Pointer field returns its address as int."""
+        class data_t(struct):
+            value: c_int
+            ref: c_long
+


The test name/docstring says this is a pointer field, but the struct defines ref: c_long (a plain integer). Either change the field to an actual ptr/ptr_to(...) field, or update the docstring to reflect that this test is about serializing raw address-like integers rather than pointer descriptors.

Copilot

Pull request overview

Copilot reviewed 77 out of 77 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-01T18:01:22Z

libdestruct/libdestruct.py

+def inflater(memory: Sequence, endianness: str = "little") -> Inflater:
    """Return a TypeInflater instance."""
    if not isinstance(memory, Sequence):
-        raise TypeError(f"memory must be a MutableSequence, not {type(memory).__name__}")
+        raise TypeError(f"memory must be a Sequence, not {type(memory).__name__}")
+


inflater() now accepts any Sequence, which includes str. Passing a string will pass this check but then fail later in MemoryResolver.resolve() when bytes(self.memory[...]) is called. Consider restricting memory to bytes-like buffers (e.g., bytes, bytearray, memoryview) or explicitly rejecting str/non-bytes sequences to fail fast with a clear error.

Copilot · 2026-04-01T18:01:22Z

libdestruct/common/union/__init__.py

+import libdestruct.common.union.tagged_union_field_inflater
+import libdestruct.common.union.union_field_inflater  # noqa: F401


This import is only for side effects (handler registration) but lacks # noqa: F401, so Ruff will flag it as an unused import. Add # noqa: F401 (as done for union_field_inflater) or otherwise reference it explicitly.

Copilot · 2026-04-01T18:01:23Z

docs/advanced/forward_refs.md

+This means the referenced type must be defined before the struct is inflated, but not necessarily before it is declared.
+
+!!! info
+    Forward references are resolved through the `TypeRegistry` at inflation time. If the referenced type is not found, an error is raised.


The note says an error is raised if a forward-referenced type is not found, but the current implementation for ptr["TypeName"] uses lazy resolution and can silently fall back to an untyped ptr when the reference can’t be resolved. Please either update the docs to match the behavior or tighten the implementation to raise a clear error when the forward ref can’t be resolved.

Suggested change

Forward references are resolved through the `TypeRegistry` at inflation time. If the referenced type is not found, an error is raised.

Forward references are resolved through the `TypeRegistry` at inflation time using lazy resolution.

If the referenced type name cannot be resolved at that point, libdestruct falls back to an untyped/generic `ptr`

rather than raising an immediate error. Be aware that misspelled or missing type names may therefore not fail fast

and can instead surface later as unexpected runtime behavior.

Copilot · 2026-04-01T18:01:23Z

docs/memory/resolvers.md

+| `resolve(size, offset)` | Read `size` bytes starting at the resolved address + offset |
+| `resolve_address()` | Return the absolute address of this resolver |
+| `modify(size, index, value)` | Write `value` bytes at the resolved address + index |
+| `relative_from_own(offset, size)` | Create a child resolver at a relative offset |


The documented relative_from_own(offset, size) signature doesn’t match the actual Resolver.relative_from_own(address_offset, index_offset) interface used in the codebase. Update the docs to reflect the correct parameter meaning/name to avoid confusion for custom resolver implementers.

Suggested change

| `relative_from_own(offset, size)` | Create a child resolver at a relative offset |

| `relative_from_own(address_offset, index_offset)` | Create a child resolver at a relative address and index offset |

Copilot · 2026-04-01T18:01:23Z

docs/memory/resolvers.md

+### FakeResolver
+
+A resolver backed by a simulated 4KB memory page, used internally when you create structs via keyword arguments or `from_bytes()` without explicit memory:
+


This section states that FakeResolver is used for from_bytes() without explicit memory, but obj.from_bytes() / struct.from_bytes() currently build an Inflater over the provided bytes and therefore use MemoryResolver (not FakeResolver). Consider updating the docs to mention only the kwargs/no-buffer construction path (e.g., test_t(a=42)).

Copilot

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-03T05:31:43Z

libdestruct/libdestruct.py

+def inflater(memory: Sequence | mmap.mmap, endianness: str = "little") -> Inflater:
    """Return a TypeInflater instance."""
-    if not isinstance(memory, Sequence):
-        raise TypeError(f"memory must be a MutableSequence, not {type(memory).__name__}")
+    if not isinstance(memory, Sequence | mmap.mmap):
+        raise TypeError(f"memory must be a Sequence, not {type(memory).__name__}")
+
+    if endianness not in _VALID_ENDIANNESS:
+        raise ValueError(f"endianness must be 'little' or 'big', not {endianness!r}")


isinstance() does not accept a PEP-604 union (Sequence | mmap.mmap) as its second argument. This will raise TypeError at runtime on all supported Python versions. Use a tuple of types instead (e.g., (Sequence, mmap.mmap)).

Copilot · 2026-04-03T05:31:43Z

libdestruct/common/obj.py

+            # Guard against incompatible value types (e.g. int vs str from struct.get())
+            if type(self_val) is not type(other_val) and not isinstance(self_val, type(other_val)) and not isinstance(other_val, type(self_val)):
+                return None
+            return self_val, other_val
+        if isinstance(other, int | float | bytes):
+            return self_val, other
+        return None


isinstance(other, int | float | bytes) will raise TypeError because isinstance() expects a type or tuple of types, not a PEP-604 union. This breaks all comparison operators that call _compare_value. Use isinstance(other, (int, float, bytes)) instead.

Copilot · 2026-04-03T05:31:44Z

libdestruct/common/array/__init__.py

+__all__ = ["array", "array_of", "vla_of"]

-import libdestruct.common.array.array_field_inflater  # noqa: F401
+import libdestruct.common.array.array_field_inflater
+import libdestruct.common.array.vla_field_inflater  # noqa: F401 — side-effect: registers VLA handler


This import is only used for its side effects (handler registration) but is currently unannotated. ruff check (run in CI) will flag it as F401 unused import. Add # noqa: F401 (or assign to _) to document the intent and satisfy the linter.

MrIndeciso added 30 commits July 15, 2025 15:08

style: refactor project

617abe2

fix: correct various problems in the codebase

60ebfe0

test: add general check for issue #6

e282510

fix: cast to bytes in MemoryResolver instead of returning the slice d…

85fcd48

…irectly

test: add more test coverage on the entire codebase

7bc1802

fix: avoid name clashes with address and other members

69f2657

docs: add main README for the repository

919e79e

docs: add basic project documentation

3778fda

feat: implement bitfield support

570dea3

docs: add bitfield documentation

54ef86a

test: add bitfield tests

9aeae00

test: add tests for c_float and c_double

c6cfefc

fix: add missing support for c_float and c_double

9ff0e22

feat: add support for pointer arithmetics

86e7a07

docs: add documentation about pointer arithmetics

1e1ed75

feat: add support for typedefs in C-to-Python struct parsing

46e2d14

docs: add documentation for typedef support in C struct parsing

5e8dd5a

feat: publicly exposed size_of method

40ec6b3

docs: add documentation about size_of

ca3487f

feat: implement hexdump functionality for all objects

69be136

docs: add guide for hexdump formatting

bda7078

fix: implement caching for dereferenced pointer objects

03505ab

docs: add explanation about pointer caching

2e5b7da

chore: create SKILL.md file for AI agents

59f970e

fix: export c_char, c_uchar, c_short, c_ushort too

57def08

feat: add comparison operators for libdestruct objects

911550e

feat: add support for simple and tagged unions

628bd37

test: add checks for tagged and simple unions

25d7e5b

docs: add documentation for simple and tagged unions

5915b3e

feat: add quick to_dict() method to all objects

ee22756

MrIndeciso added 7 commits March 31, 2026 19:42

feat: add support for alignment in structs

dd6df6b

fix: solve various issues in the codebase that Opus created and then …

0c501ee

…fixed itself

feat: add big-endian support in the resolver

7af03fe

This propagates down the chain, and everything works big-endian

fix: struct freezing didn't work correctly, alignment was broken for …

837c574

…arrays

style: hide incorrect linter annotation

fe0353d

ci: run test suite on all python versions we support

fffff7f

feat: implement the proposal in issue #5

726f12d

MrIndeciso requested a review from Copilot April 1, 2026 14:09

Copilot started reviewing on behalf of MrIndeciso April 1, 2026 14:10 View session

MrIndeciso added 2 commits April 1, 2026 09:14

feat: add support for modifiers like offset specified through Annotat…

88b489f

…ed types

docs: change docs to use the new declarative types and Annotated fields

baa56de

Copilot AI reviewed Apr 1, 2026

View reviewed changes

MrIndeciso added 3 commits April 1, 2026 11:04

fix: CoPilot noticed a few smaller mistakes

2a849b6

fix: solve incorrect union alignment and enum backing type assumptions

b39a993

fix: Opus found even more bugs, everything should be fixed now

f134091

MrIndeciso requested a review from Copilot April 1, 2026 17:31

Copilot started reviewing on behalf of MrIndeciso April 1, 2026 17:32 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

fix: correct wrong enum_of implementation in code and docs

8b8ca90

MrIndeciso requested a review from Copilot April 1, 2026 17:53

Copilot started reviewing on behalf of MrIndeciso April 1, 2026 17:53 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

MrIndeciso added 3 commits April 1, 2026 13:08

test/docs: automatically check doc snippets to verity their correctness

f71009a

feat: implement support for VLAs and file-backed inflaters

6bf5c45

fix: solve the last remaining bugs I could find in the codebase

7c0a412

MrIndeciso requested a review from Copilot April 3, 2026 05:26

Copilot started reviewing on behalf of MrIndeciso April 3, 2026 05:26 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

		size_of(array[c_int, 10]) # 40
		size_of(array_of(c_int, 10)) # 40 (legacy syntax)

	size_of(array[c_int, 10]) # 40
	size_of(array_of(c_int, 10)) # 40 (legacy syntax)
	size_of(array_of(c_int, 10)) # 40

		import libdestruct.common.union.tagged_union_field_inflater
		import libdestruct.common.union.union_field_inflater # noqa: F401

-    Forward references are resolved through the `TypeRegistry` at inflation time. If the referenced type is not found, an error is raised.
+    Forward references are resolved through the `TypeRegistry` at inflation time using lazy resolution.
+    If the referenced type name cannot be resolved at that point, libdestruct falls back to an untyped/generic `ptr`
+    rather than raising an immediate error. Be aware that misspelled or missing type names may therefore not fail fast
+    and can instead surface later as unexpected runtime behavior.

	\| `relative_from_own(offset, size)` \| Create a child resolver at a relative offset \|
	\| `relative_from_own(address_offset, index_offset)` \| Create a child resolver at a relative address and index offset \|

		### FakeResolver

		A resolver backed by a simulated 4KB memory page, used internally when you create structs via keyword arguments or `from_bytes()` without explicit memory:

Conversation

MrIndeciso commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

MrIndeciso commented Apr 1, 2026 •

edited

Loading