Type annotations reference

Char = bytes module-attribute

Single char type. Supported in both size modes.

Bool = Annotated[bool, field.BoolField()] module-attribute

Boolean type. Supported in both size modes.

I8 = Annotated[int, field.SignedStdIntField(1)] module-attribute

Fixed-width 8-bit signed integer. Supported with size="std".

U8 = Annotated[int, field.UnsignedStdIntField(1)] module-attribute

Fixed-width 8-bit unsigned integer. Supported with size="std".

I16 = Annotated[int, field.SignedStdIntField(2)] module-attribute

Fixed-width 16-bit signed integer. Supported with size="std".

U16 = Annotated[int, field.UnsignedStdIntField(2)] module-attribute

Fixed-width 16-bit unsigned integer. Supported with size="std".

I32 = Annotated[int, field.SignedStdIntField(4)] module-attribute

Fixed-width 32-bit signed integer. Supported with size="std".

U32 = Annotated[int, field.UnsignedStdIntField(4)] module-attribute

Fixed-width 32-bit unsigned integer. Supported with size="std".

I64 = Annotated[int, field.SignedStdIntField(8)] module-attribute

Fixed-width 64-bit signed integer. Supported with size="std".

U64 = Annotated[int, field.UnsignedStdIntField(8)] module-attribute

Fixed-width 64-bit unsigned integer. Supported with size="std".

SignedChar = Annotated[int, field.NativeIntField('b', 'byte')] module-attribute

Equivalent to native C signed char. Supported with size="native".

UnsignedChar = Annotated[int, field.NativeIntField('B', 'ubyte')] module-attribute

Equivalent to native C unsigned char. Supported with size="native".

Short = Annotated[int, field.NativeIntField('h', 'short')] module-attribute

Equivalent to native C short. Supported with size="native".

UnsignedShort = Annotated[int, field.NativeIntField('H', 'ushort')] module-attribute

Equivalent to native C unsigned short. Supported with size="native".

Int = Annotated[int, field.NativeIntField('i', 'int')] module-attribute

Equivalent to native C int. Supported with size="native".

UnsignedInt = Annotated[int, field.NativeIntField('I', 'uint')] module-attribute

Equivalent to native C unsigned int. Supported with size="native".

Long = Annotated[int, field.NativeIntField('l', 'long')] module-attribute

Equivalent to native C long. Supported with size="native".

UnsignedLong = Annotated[int, field.NativeIntField('L', 'ulong')] module-attribute

Equivalent to native C unsigned long. Supported with size="native".

LongLong = Annotated[int, field.NativeIntField('q', 'longlong')] module-attribute

Equivalent to native C long long. Supported with size="native".

UnsignedLongLong = Annotated[int, field.NativeIntField('Q', 'ulonglong')] module-attribute

Equivalent to native C unsigned long long. Supported with size="native".

UnsignedSize = Annotated[int, field.SizeField(signed=False)] module-attribute

Equivalent to native C size_t. Supported with size="native".

SignedSize = Annotated[int, field.SizeField(signed=True)] module-attribute

Equivalent to native C ssize_t (a POSIX extension type). Supported with size="native".

Pointer = Annotated[int, field.PointerField()] module-attribute

Equivalent to native C void * pointer. Supported with size="native".

F16 = Annotated[float, field.FloatingPointField('e')] module-attribute

Half-precision floating point number. Supported in both size modes.

Some compilers provide support for half precision floats on certain platforms (e.g. GCC, Clang). It is also available as std::float16_t in C++23.

F32 = Annotated[float, field.FloatingPointField('f')] module-attribute

Single-precision floating point number, equivalent to float in C. Supported in both size modes.

F64 = Annotated[float, field.FloatingPointField('d')] module-attribute

Double-precision floating point number, equivalent to double in C. Supported in both size modes.

LengthPrefixed

Bases: Field[bytes]

Length-prefixed byte array, also known as a 'Pascal string'.

Packed to a fixed-length array of bytes, where the first byte is the length of the data. Data shorter than the maximum size is padded with zero bytes.

Must be used to annotate a bytes field with typing.Annotated:

import dataclasses_struct as dcs

@dcs.dataclass_struct()
class Example:
    fixed_length: Annotated[bytes, dcs.LengthPrefixed(10)]

Parameters:

Name	Type	Description	Default
size	int	The maximum size of the string including the length byte. Must be between 2 and 256 inclusive. The maximum array length that can be stored without truncation is size - 1.	required

Raises:

Type	Description
ValueError	If size is outside the valid range.

Source code in dataclasses_struct/types.py

class LengthPrefixed(field.Field[bytes]):
    """
    Length-prefixed byte array, also known as a 'Pascal string'.

    Packed to a fixed-length array of bytes, where the first byte is the length
    of the data. Data shorter than the maximum size is padded with zero bytes.

    Must be used to annotate a `bytes` field with `typing.Annotated`:

    ```python
    import dataclasses_struct as dcs

    @dcs.dataclass_struct()
    class Example:
        fixed_length: Annotated[bytes, dcs.LengthPrefixed(10)]
    ```

    Args:
        size: The maximum size of the string including the length byte. Must be
            between 2 and 256 inclusive. The maximum array length that can be
            stored without truncation is `size - 1`.

    Raises:
        ValueError: If `size` is outside the valid range.
    """

    field_type = bytes

    def __init__(self, size: int):
        if not (isinstance(size, int) and 2 <= size <= 256):
            raise ValueError("size must be an int between 2 and 256")
        self.size = size

    def format(self) -> str:
        return f"{self.size}p"

    def __repr__(self) -> str:
        return f"{type(self).__name__}({self.size})"

    def validate_default(self, val: bytes) -> None:
        if len(val) > self.size - 1:
            msg = f"bytes cannot be longer than {self.size - 1} bytes"
            raise ValueError(msg)

NullTerminated

Bases: Field[bytes]

Null-terminated byte array, commonly known as a 'C string'.

Packed to a fixed-length array of bytes of length size that is guaranteed to be null-terminated. Note that size includes the null byte, so arrays longer than size - 1 are truncated.

When unpacking, the trailing null byte and any subsequent bytes are discarded.

Must be used to annotate a bytes field with typing.Annotated. For example,

import dataclasses_struct as dcs

@dcs.dataclass_struct()
class Example:
    cstr: Annotated[bytes, dcs.NullTerminated(5)]

>>> example = Example(b"123")
>>> packed = example.pack()
>>> packed
b'123'
>>> unpacked = Example.from_packed(packed)
>>> unpacked
Example(cstr=b'123')

Note that there is additional overhead when unpacking as the bytes array is searched for the null terminator. If this is a concern (e.g. for very large arrays), it may be better to just use a regular fixed-length bytes array with a single trailing pad byte to ensure the array is always null-terminated. E.g. the following

@dcs.dataclass_struct()
class Test:
    array: Annotated[bytes, LENGTH, dcs.PadAfter(1)]

is equivalent to the following array declaration in C:

struct Test {
    unsigned char array[LENGTH + 1];
};

Parameters:

Name	Type	Description	Default
size	int	The total size of the byte array, including the trailing null byte.	required

Raises:

Type	Description
ValueError	If size is not a positive, non-zero integer.

Source code in dataclasses_struct/types.py

class NullTerminated(field.Field[bytes]):
    """
    Null-terminated byte array, commonly known as a 'C string'.

    Packed to a fixed-length array of bytes of length `size` that is guaranteed
    to be null-terminated. Note that `size` includes the null byte, so arrays
    longer than `size - 1` are truncated.

    When unpacking, the trailing null byte and any subsequent bytes are
    discarded.

    Must be used to annotate a `bytes` field with `typing.Annotated`. For
    example,

    ```python
    import dataclasses_struct as dcs

    @dcs.dataclass_struct()
    class Example:
        cstr: Annotated[bytes, dcs.NullTerminated(5)]
    ```

    ```python
    >>> example = Example(b"123")
    >>> packed = example.pack()
    >>> packed
    b'123\x00\x00'
    >>> unpacked = Example.from_packed(packed)
    >>> unpacked
    Example(cstr=b'123')
    ```

    Note that there is additional overhead when unpacking as the bytes array is
    searched for the null terminator. If this is a concern (e.g. for very large
    arrays), it may be better to just use a regular fixed-length bytes array
    with a single trailing pad byte to ensure the array is always
    null-terminated. E.g. the following

    ```python
    @dcs.dataclass_struct()
    class Test:
        array: Annotated[bytes, LENGTH, dcs.PadAfter(1)]
    ```

    is equivalent to the following array declaration in C:

    ```c
    struct Test {
        unsigned char array[LENGTH + 1];
    };
    ```

    Args:
        size: The total size of the byte array, including the trailing null
            byte.

    Raises:
        ValueError: If `size` is not a positive, non-zero integer.
    """

    field_type = bytes

    def __init__(self, size: int):
        if not isinstance(size, int) or size <= 0:
            raise ValueError(
                "null-terminated string length must be positive non-zero int"
            )

        self.size = size

    def __repr__(self) -> str:
        return f"{type(self).__name__}({self.size})"

    def format(self) -> str:
        return f"{self.size - 1}sx"

    def validate_default(self, val: bytes) -> None:
        n = len(val)
        if n >= self.size:
            msg = (
                "null-terminated string cannot be longer than"
                f" {self.size - 1} bytes (size includes the null terminator)"
            )
            raise ValueError(msg)

PadBefore

Bases: _Padding

Add zero-bytes padding before the field.

Should be used with typing.Annotated.

from typing import Annotated
import dataclasses_struct as dcs

@dcs.dataclass_struct()
class Padded:
    x: Annotated[int, dcs.PadBefore(5)]

Parameters:

Name	Type	Description	Default
size	int	The number of padding bytes to add before the field.	required

Source code in dataclasses_struct/types.py

class PadBefore(_Padding):
    """Add zero-bytes padding before the field.

    Should be used with `typing.Annotated`.

    ```python
    from typing import Annotated
    import dataclasses_struct as dcs

    @dcs.dataclass_struct()
    class Padded:
        x: Annotated[int, dcs.PadBefore(5)]
    ```

    Args:
        size: The number of padding bytes to add before the field.
    """

    before = True

    def __init__(self, size: int):
        super().__init__(size)

PadAfter

Bases: _Padding

Add zero-bytes padding after the field.

Should be used with typing.Annotated.

from typing import Annotated
import dataclasses_struct as dcs

@dcs.dataclass_struct()
class Padded:
    x: Annotated[int, dcs.PadAfter(5)]

Parameters:

Name	Type	Description	Default
size	int	The number of padding bytes to add after the field.	required

Source code in dataclasses_struct/types.py

class PadAfter(_Padding):
    """Add zero-bytes padding after the field.

    Should be used with `typing.Annotated`.

    ```python
    from typing import Annotated
    import dataclasses_struct as dcs

    @dcs.dataclass_struct()
    class Padded:
        x: Annotated[int, dcs.PadAfter(5)]
    ```

    Args:
        size: The number of padding bytes to add after the field.
    """

    before = False

    def __init__(self, size: int):
        super().__init__(size)