Special Fields

Special-purpose fields for common binary data patterns.

Available Types

• Bool - Boolean value (1 byte)

• Padding - Skip bytes (ignored during parsing)

• Flags - Bit flags with named flags

• Enum - Enum value mapping

Bool

Boolean field (1 byte, 0=False, non-zero=True):

from pystructs import Struct, Bool

class Settings(Struct):
    enabled = Bool(default=True)
    verbose = Bool(default=False)

s = Settings.parse(b"\x01\x00")
print(s.enabled)  # True
print(s.verbose)  # False

Padding

Skip bytes during parsing, fill with value during serialization:

from pystructs import Struct, UInt8, Padding

class AlignedData(Struct):
    value = UInt8()
    _pad = Padding(size=3)  # Align to 4 bytes
    next_value = UInt32()

Flags

Bit flags with named flag values:

from pystructs import Struct, Flags

class FileDescriptor(Struct):
    permissions = Flags(
        size=2,
        flags={
            "READ": 0x01,
            "WRITE": 0x02,
            "EXECUTE": 0x04,
        },
    )

fd = FileDescriptor.parse(b"\x03\x00")
print("READ" in fd.permissions)   # True
print("WRITE" in fd.permissions)  # True
print("EXECUTE" in fd.permissions)  # False

Enum

Map integer values to enum members:

from enum import IntEnum
from pystructs import Struct, Enum

class MessageType(IntEnum):
    REQUEST = 1
    RESPONSE = 2
    ERROR = 3

class Message(Struct):
    msg_type = Enum(MessageType, size=1)

msg = Message.parse(b"\x02")
print(msg.msg_type)  # MessageType.RESPONSE
print(msg.msg_type == MessageType.RESPONSE)  # True

API Reference

class pystructs.fields.special.Bool(default: bool | None = None, required: bool = True, validators: List[Callable] | None = None)

Boolean field (1 byte).

Reads/writes a single byte where 0 is False and non-zero is True.

Examples:

>>> class Message(Struct):
...     is_active = Bool()
...     has_payload = Bool(default=False)

parse(buffer: BinaryIO, instance: Struct) → bool

Parse a boolean from buffer.

Args:

buffer: Binary stream to read from instance: The struct instance being parsed

Returns:

Parsed boolean value

Raises:

UnexpectedEOF: If not enough bytes available

serialize(value: bool, instance: Struct) → bytes

Serialize a boolean to bytes.

Args:

value: The boolean value to serialize instance: The struct instance being serialized

Returns:

Serialized bytes (0x00 or 0x01)

class pystructs.fields.special.Padding(size: int | Ref, fill: int = 0)

Padding bytes that are ignored during parsing.

Padding is used to align fields or skip reserved bytes. The padding bytes are not stored in the struct.

Examples:

>>> class AlignedData(Struct):
...     value = UInt8()
...     _pad = Padding(size=3)  # Align to 4 bytes
...     data = UInt32()

get_size(instance: Struct) → int

Get the size of the padding.

Args:

instance: The struct instance

Returns:

Size in bytes

parse(buffer: BinaryIO, instance: Struct) → None

Parse (skip) padding bytes from buffer.

Args:

buffer: Binary stream to read from instance: The struct instance being parsed

Returns:

None (padding is not stored)

Raises:

UnexpectedEOF: If not enough bytes available

serialize(value: Any, instance: Struct) → bytes

Serialize padding bytes.

Args:

value: Ignored (padding has no value) instance: The struct instance being serialized

Returns:

Padding bytes filled with the fill value

class pystructs.fields.special.Flags(size: int, flags: Dict[str, int], default: Set[str] | None = None, required: bool = True, validators: List[Callable] | None = None)

Bit flags field.

Maps individual bits to named flags, returning a FlagSet.

Examples:

>>> class Permission(Struct):
...     flags = Flags(
...         size=1,
...         flags={
...             'READ': 0x01,
...             'WRITE': 0x02,
...             'EXECUTE': 0x04,
...         }
...     )
...
>>> p = Permission.parse(b'\x05')
>>> 'READ' in p.flags
True
>>> 'EXECUTE' in p.flags
True
>>> 'WRITE' in p.flags
False

get_size(instance: Struct) → int

Get the size of the flags field.

Args:

instance: The struct instance

Returns:

Size in bytes

parse(buffer: BinaryIO, instance: Struct) → FlagSet

Parse flags from buffer.

Args:

buffer: Binary stream to read from instance: The struct instance being parsed

Returns:

FlagSet with active flag names

Raises:

UnexpectedEOF: If not enough bytes available

serialize(value: FlagSet | Set[str] | int, instance: Struct) → bytes

Serialize flags to bytes.

Args:

value: FlagSet, set of flag names, or raw integer instance: The struct instance being serialized

Returns:

Serialized bytes

class pystructs.fields.special.Enum(enum_class: Type[IntEnum], size: int = 1, default: IntEnum | None = None, required: bool = True, validators: List[Callable] | None = None)

Enum field that maps integer values to enum members.

Uses Python’s enum module for type-safe enum handling.

Examples:

>>> from enum import IntEnum
>>>
>>> class MessageType(IntEnum):
...     REQUEST = 1
...     RESPONSE = 2
...     ERROR = 3
...
>>> class Message(Struct):
...     msg_type = Enum(MessageType, size=1)
...
>>> m = Message.parse(b'\x02')
>>> m.msg_type
<MessageType.RESPONSE: 2>
>>> m.msg_type == MessageType.RESPONSE
True

get_size(instance: Struct) → int

Get the size of the enum field.

Args:

instance: The struct instance

Returns:

Size in bytes

parse(buffer: BinaryIO, instance: Struct) → _enum.IntEnum

Parse enum from buffer.

Args:

buffer: Binary stream to read from instance: The struct instance being parsed

Returns:

Enum member

Raises:

UnexpectedEOF: If not enough bytes available ValueError: If value is not a valid enum member

serialize(value: _enum.IntEnum | int, instance: Struct) → bytes

Serialize enum to bytes.

Args:

value: Enum member or raw integer instance: The struct instance being serialized

Returns:

Serialized bytes