feat: Struct-level Alignment (AlignTo)

docs/sphinx/source/library/fields/common.rst

@@ -331,6 +331,18 @@ Special Structs
 
     .. versionadded:: 2.4.0
 
+.. autoclass:: caterpillar.fields.AlignTo
+    :members:
+
+    A trailing, self-contained alignment spec used via the ``align_to=``
+    keyword on :func:`~caterpillar.py.struct`, :func:`~caterpillar.py.union`
+    and :func:`~caterpillar.py.bitfield`. Unlike :class:`Aligned`, which pads
+    relative to the *absolute* stream position, ``align_to=`` pads the model
+    itself so its own packed size is always a multiple of the alignment -
+    regardless of where it is embedded. See :ref:`tutorial-align_to`.
+
+    .. versionadded:: 2.10.0
+
 .. autoclass:: caterpillar.fields.Computed
     :members:
 

docs/sphinx/source/library/model/bitfield.rst

@@ -89,6 +89,11 @@ Main Interface
     .. versionchanged:: 2.5.0
         Added the ``alignment`` parameter.
 
+    .. versionchanged:: 2.10.0
+        Added the ``align_to`` parameter for whole-bitfield trailing byte
+        alignment (distinct from the bit-group ``alignment`` parameter
+        above). See :ref:`tutorial-align_to`.
+
 Default Factory Classes
 -----------------------
 

docs/sphinx/source/library/model/struct.rst

@@ -29,6 +29,12 @@ Standard Interface
 
 .. autofunction:: caterpillar.model.struct
 
+    .. versionchanged:: 2.10.0
+        Added the ``align_to`` parameter (also accepted by :func:`union`
+        above) for whole-model trailing byte alignment. See
+        :ref:`tutorial-align_to`.
+
+
 .. autofunction:: caterpillar.model.pack
 
 .. autofunction:: caterpillar.model.pack_into

docs/sphinx/source/tutorial/basics/padding.rst

@@ -16,3 +16,71 @@ length using the `padding` keyword. This is useful when you need to ensure
 that certain fields are aligned or when the structure requires reserved spaces.
 
 >>> field = padding[10] # greedy or dynamic size
+
+
+.. _tutorial-align_to:
+
+Whole-model alignment
+----------------------
+
+.. versionadded:: 2.10.0
+
+The :code:`padding` field above reserves space explicitly, as an extra field
+of its own. Sometimes what you actually want is different: a whole
+:code:`@struct`, :code:`@union` or :code:`@bitfield` class whose *total*
+packed size is always rounded up to a multiple of some alignment.
+Pass :code:`align_to=` to the decorator instead:
+
+>>> @struct(align_to=4)
+... class Format:
+...     a: uint8
+...
+>>> sizeof(Format)
+4
+>>> unpack(Format, b"\x01\x00\x00\x00")
+Format(a=1)
+
+This is deliberately different from :class:`~caterpillar.fields.Aligned` and
+:func:`~caterpillar.fields.align`, which both pad relative to the *absolute*
+stream position. :code:`align_to=` instead measures *this model's own* start
+and end, so the padding only ever depends on the model's own content - not on
+where it happens to be embedded:
+
+>>> @struct
+... class Outer:
+...     b: uint8
+...     inner: Format
+...     c: uint8
+...
+>>> pack(Outer(b=1, inner=Format(a=2), c=3))
+b'\x01\x02\x00\x00\x00\x03'
+
+A bare :code:`int` or context lambda is accepted directly, as shown above.
+Use :class:`~caterpillar.fields.AlignTo` explicitly to customize the fill
+byte (or a multi-byte fill pattern) and/or relax verification:
+
+>>> @struct(align_to=AlignTo(4, fill=0xFF, strict=False))
+... class Lenient:
+...     a: uint8
+
+With the default :code:`strict=True`, unpacking verifies that the padding
+bytes actually match :code:`fill` and raises :code:`ValueError` if they
+don't. With :code:`strict=False`, padding bytes are consumed without
+verification.
+
+:code:`align_to=` also works on :code:`@union` (padding after the largest
+member) and :code:`@bitfield` (padding after all bit-groups have been
+finalized to whole bytes), and applies per-element when the model is used
+inside an array, so each element keeps its own alignment:
+
+>>> @struct
+... class Many:
+...     items: Format[2]
+...
+>>> pack(Many(items=[Format(a=1), Format(a=2)]))
+b'\x01\x00\x00\x00\x02\x00\x00\x00'
+
+A dynamic (context-dependent) alignment value is supported too, but makes the
+model's size undeterminable ahead of time - :func:`~caterpillar.model.sizeof`
+raises :class:`~caterpillar.exception.DynamicSizeError` in that case.
+

src/caterpillar/fields/__init__.py

@@ -12,11 +12,19 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
-from ._base import DEFAULT_OPTION, INVALID_DEFAULT, Field, singleton
+from ._base import (
+    DEFAULT_OPTION,
+    IGNORED_DEFAULT,
+    INVALID_DEFAULT,
+    Field,
+    has_default,
+    singleton,
+)
 from ._mixin import Chain, FieldMixin, FieldStruct, Operator, get_args, get_kwargs
 from .common import (
     ENUM_STRICT,
     Aligned,
+    AlignTo,
     AsLengthRef,
     Bytes,
     Computed,
@@ -144,147 +152,153 @@
     uintptr,
     uintptr_fn,
 )
+from .unnamed import Unnamed, sized
 from .varint import VARINT_LSB, VarInt, vint
 
 __all__ = [
+    "CTX_DIGEST",
+    "CTX_DIGEST_ALGO",
+    "CTX_DIGEST_HOOK",
+    "CTX_DIGEST_OBJ",
+    "DEFAULT_OPTION",
+    "ENUM_STRICT",
+    "HMAC",
+    "IGNORED_DEFAULT",
+    "INVALID_DEFAULT",
+    "MAC",
+    "PTR_STRICT",
+    "VARINT_LSB",
+    "Adler",
     "Adler_Algo",
     "Adler_Field",
-    "Adler",
     "Algorithm",
-    "align",
+    "AlignTo",
     "Aligned",
     "And",
     "AsLengthRef",
-    "boolean",
     "Branch",
     "Bytes",
     "Bz2Compressed",
+    "CString",
     "Chain",
-    "char",
     "Compressed",
     "Computed",
     "ConditionalChain",
     "Const",
     "ConstBytes",
     "ConstString",
+    "Crc32",
     "Crc32_Algo",
     "Crc32_Field",
-    "Crc32",
-    "CString",
-    "CTX_DIGEST_ALGO",
-    "CTX_DIGEST_HOOK",
-    "CTX_DIGEST_OBJ",
-    "CTX_DIGEST",
-    "DEFAULT_OPTION",
     "Digest",
     "DigestField",
     "DigestFieldAction",
-    "double",
     "Else",
     "ElseIf",
     "Encrypted",
     "End",
-    "ENUM_STRICT",
     "Enum",
     "Field",
     "FieldMixin",
     "FieldStruct",
-    "float16",
-    "float32",
-    "float64",
-    "get_args",
-    "get_kwargs",
-    "HMAC",
     "HMACAlgorithm",
-    "If",
-    "Int",
-    "int16",
-    "int24",
-    "int32",
-    "int64",
-    "int8",
-    "intptr_fn",
-    "intptr",
-    "INVALID_DEFAULT",
     "IOHook",
     "IPv4Address",
     "IPv6Address",
+    "If",
+    "Int",
     "KeyCipher",
-    "Lazy",
     "LZMACompressed",
     "LZOCompressed",
-    "MAC",
+    "Lazy",
     "MACAddress",
+    "Md5",
     "Md5_Algo",
     "Md5_Field",
-    "Md5",
     "Memory",
-    "offintptr",
-    "offuintptr",
     "Operator",
     "Or",
     "Otherwise",
     "Padded",
-    "padding",
     "Padding",
     "Pass",
-    "pointer",
     "Pointer",
     "PostPad",
-    "Prefixed",
     "PrePad",
-    "psize",
-    "pssize",
-    "PTR_STRICT",
+    "Prefixed",
     "PyStructFormattedField",
-    "relative_pointer",
     "RelativePointer",
+    "Sha1",
     "Sha1_Algo",
     "Sha1_Field",
-    "Sha1",
+    "Sha2_224",
     "Sha2_224_Algo",
     "Sha2_224_Field",
-    "Sha2_224",
+    "Sha2_256",
     "Sha2_256_Algo",
     "Sha2_256_Field",
-    "Sha2_256",
+    "Sha2_384",
     "Sha2_384_Algo",
     "Sha2_384_Field",
-    "Sha2_384",
+    "Sha2_512",
     "Sha2_512_Algo",
     "Sha2_512_Field",
-    "Sha2_512",
+    "Sha3_224",
     "Sha3_224_Algo",
     "Sha3_224_Field",
-    "Sha3_224",
+    "Sha3_256",
     "Sha3_256_Algo",
     "Sha3_256_Field",
-    "Sha3_256",
+    "Sha3_384",
     "Sha3_384_Algo",
     "Sha3_384_Field",
-    "Sha3_384",
+    "Sha3_512",
     "Sha3_512_Algo",
     "Sha3_512_Field",
-    "Sha3_512",
-    "singleton",
     "Start",
     "String",
     "Timestamp",
     "Transformer",
     "UInt",
+    "Unnamed",
+    "Uuid",
+    "VarInt",
+    "When",
+    "Xor",
+    "ZLibCompressed",
+    "align",
+    "boolean",
+    "char",
+    "double",
+    "float16",
+    "float32",
+    "float64",
+    "get_args",
+    "get_kwargs",
+    "has_default",
+    "int8",
+    "int16",
+    "int24",
+    "int32",
+    "int64",
+    "intptr",
+    "intptr_fn",
+    "offintptr",
+    "offuintptr",
+    "padding",
+    "pointer",
+    "psize",
+    "pssize",
+    "relative_pointer",
+    "singleton",
+    "sized",
+    "uint8",
     "uint16",
     "uint24",
     "uint32",
     "uint64",
-    "uint8",
-    "uintptr_fn",
     "uintptr",
-    "Uuid",
-    "VARINT_LSB",
-    "VarInt",
+    "uintptr_fn",
     "vint",
     "void_ptr",
-    "When",
-    "Xor",
-    "ZLibCompressed",
 ]