feat: implement hexdump functionality for all objects

Author: MrIndeciso

libdestruct/common/hexdump.py

@@ -0,0 +1,48 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2026 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from __future__ import annotations
+
+
+def format_hexdump(
+    data: bytes,
+    base_address: int = 0,
+    annotations: dict[int, str] | None = None,
+) -> str:
+    """Format a classic hex dump of the given data.
+
+    Args:
+        data: The bytes to dump.
+        base_address: The starting address shown in the offset column.
+        annotations: Optional mapping from byte offset to field name, shown in the margin.
+
+    Returns:
+        A formatted hex dump string.
+    """
+    lines = []
+    for offset in range(0, len(data), 16):
+        chunk = data[offset : offset + 16]
+        addr = base_address + offset
+
+        hex_parts = " ".join(f"{b:02x}" for b in chunk)
+        # Pad to full 16-byte width
+        hex_parts = hex_parts.ljust(47)
+
+        ascii_parts = "".join(chr(b) if chr(b).isprintable() and b < 128 else "." for b in chunk)  # noqa: PLR2004
+
+        line = f"{addr:08x}  {hex_parts}  |{ascii_parts}|"
+
+        # Add field annotations for this line
+        if annotations:
+            fields_on_line = [
+                name for byte_offset, name in sorted(annotations.items()) if offset <= byte_offset < offset + 16
+            ]
+            if fields_on_line:
+                line += "  " + ", ".join(fields_on_line)
+
+        lines.append(line)
+
+    return "\n".join(lines)

libdestruct/common/obj.py

@@ -9,6 +9,8 @@
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Generic, TypeVar
 
+from libdestruct.common.hexdump import format_hexdump
+
 if TYPE_CHECKING:  # pragma: no cover
     from libdestruct.backing.resolver import Resolver
 
@@ -135,6 +137,11 @@ def __eq__(self: obj, value: object) -> bool:
 
         return self.get() == value.get()
 
+    def hexdump(self: obj) -> str:
+        """Return a hex dump of this object's bytes."""
+        address = self.address if not self._frozen else 0
+        return format_hexdump(self.to_bytes(), address)
+
     def __bytes__(self: obj) -> bytes:
         """Return the serialized object."""
         return self.to_bytes()

libdestruct/common/struct/struct_impl.py

@@ -14,6 +14,7 @@
 from libdestruct.common.bitfield.bitfield_field import BitfieldField
 from libdestruct.common.bitfield.bitfield_tracker import BitfieldTracker
 from libdestruct.common.field import Field
+from libdestruct.common.hexdump import format_hexdump
 from libdestruct.common.obj import obj
 from libdestruct.common.struct import struct
 from libdestruct.common.type_registry import TypeRegistry
@@ -210,6 +211,17 @@ def to_bytes(self: struct_impl) -> bytes:
         """Return the serialized representation of the struct."""
         return b"".join(member.to_bytes() for member in self._members.values())
 
+    def hexdump(self: struct_impl) -> str:
+        """Return a hex dump of this struct's bytes with field annotations."""
+        annotations = {}
+        offset = 0
+        for name, member in self._members.items():
+            annotations[offset] = name
+            offset += len(member.to_bytes())
+
+        address = struct_impl.address.fget(self) if not self._frozen else 0
+        return format_hexdump(self.to_bytes(), address, annotations)
+
     def _set(self: struct_impl, _: str) -> None:
         """Set the value of the struct to the given value."""
         raise RuntimeError("Cannot set the value of a struct.")

test/scripts/types_unit_test.py

@@ -353,5 +353,58 @@ class outer(struct):
         self.assertEqual(size_of(outer), 8)
 
 
+class HexdumpTest(unittest.TestCase):
+    """Pretty hex dump."""
+
+    def test_hexdump_primitive(self):
+        data = (0x2a).to_bytes(4, "little")
+        obj = c_int.from_bytes(data)
+        result = obj.hexdump()
+        self.assertIn("2a 00 00 00", result)
+
+    def test_hexdump_struct(self):
+        class test_t(struct):
+            a: c_int
+            b: c_int
+
+        memory = b""
+        memory += (1).to_bytes(4, "little")
+        memory += (2).to_bytes(4, "little")
+        test = test_t.from_bytes(memory)
+        result = test.hexdump()
+        # Should contain field name annotations
+        self.assertIn("a", result)
+        self.assertIn("b", result)
+
+    def test_hexdump_returns_string(self):
+        obj = c_int.from_bytes((0).to_bytes(4, "little"))
+        self.assertIsInstance(obj.hexdump(), str)
+
+    def test_hexdump_offset_column(self):
+        obj = c_int.from_bytes((0).to_bytes(4, "little"))
+        result = obj.hexdump()
+        self.assertIn("00000000", result)
+
+    def test_hexdump_ascii_column(self):
+        memory = bytearray(b"ABCD")
+        lib = inflater(memory)
+        obj = lib.inflate(c_int, 0)
+        result = obj.hexdump()
+        self.assertIn("ABCD", result)
+
+    def test_hexdump_multiline(self):
+        """More than 16 bytes should produce multiple lines."""
+        class big_t(struct):
+            a: c_long
+            b: c_long
+            c: c_long
+
+        memory = b"\x00" * 24
+        test = big_t.from_bytes(memory)
+        result = test.hexdump()
+        lines = [l for l in result.strip().split("\n") if l.strip()]
+        self.assertGreater(len(lines), 1)
+
+
 if __name__ == "__main__":
     unittest.main()