Skip to content

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 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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)

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 
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
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 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
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)