Enums¶

PDC Struct uses enumeration types to configure serialization behavior. These enums provide type-safe configuration options for StructConfig.

StructMode¶

Defines the serialization mode, which fundamentally affects how data is packed and what features are available.

Value	Description
`C_COMPATIBLE`	Fixed-size binary format compatible with C structs
`DYNAMIC`	Variable-size format with header metadata for Python-to-Python use

C_COMPATIBLE Mode¶

from pdc_struct import StructConfig, StructMode

struct_config = StructConfig(mode=StructMode.C_COMPATIBLE)

Characteristics:

No header bytes in serialized output
Fixed struct size (determined at class definition)
Optional fields must have default values
Strings are null-terminated with fixed allocation
Direct binary compatibility with C struct definitions

Best for: Embedded systems, C/C++ interop, hardware protocols, file formats with fixed layouts.

DYNAMIC Mode¶

struct_config = StructConfig(mode=StructMode.DYNAMIC)

Characteristics:

4-byte header containing version and flags
Truly optional fields (can be None, not serialized when absent)
Field presence tracked via bitmap
More space-efficient for sparse data structures

Best for: Python-to-Python IPC, network protocols between Python services, flexible data serialization.

ByteOrder¶

Controls the byte ordering (endianness) for multi-byte values like integers and floats.

Value	Struct Symbol	Description
`LITTLE_ENDIAN`	`<`	Least significant byte first (x86, ARM default)
`BIG_ENDIAN`	`>`	Most significant byte first (network byte order)
`NATIVE`	`=`	Use system's native byte order

Usage Examples¶

from pdc_struct import StructConfig, ByteOrder

# Network protocols typically use big-endian (network byte order)
struct_config = StructConfig(byte_order=ByteOrder.BIG_ENDIAN)

# x86/x64 and most ARM systems use little-endian
struct_config = StructConfig(byte_order=ByteOrder.LITTLE_ENDIAN)

# Match current system (avoid for cross-platform code)
struct_config = StructConfig(byte_order=ByteOrder.NATIVE)

Byte Order Visualization¶

For the integer 0x12345678:

BIG_ENDIAN:    [0x12] [0x34] [0x56] [0x78]  (MSB first)
LITTLE_ENDIAN: [0x78] [0x56] [0x34] [0x12]  (LSB first)

Cross-Platform Compatibility

Always specify byte order explicitly when data will be exchanged between different systems. Using NATIVE can cause issues when data is shared across platforms.

StructVersion¶

Version identifier for the serialization format, used in DYNAMIC mode headers.

Value	Integer	Description
`V1`	1	Current version

from pdc_struct import StructConfig, StructVersion

struct_config = StructConfig(version=StructVersion.V1)

The version byte appears in the header of DYNAMIC mode serializations, allowing future format evolution while maintaining backward compatibility.

HeaderFlags¶

Bit flags used in DYNAMIC mode headers to describe the serialized data. This is an IntFlag enum, allowing multiple flags to be combined.

Flag	Value	Description
`LITTLE_ENDIAN`	`0x00`	Data uses little-endian byte order
`BIG_ENDIAN`	`0x01`	Data uses big-endian byte order
`HAS_OPTIONAL_FIELDS`	`0x02`	Field presence bitmap follows header

Header Structure (DYNAMIC Mode)¶

Byte 0: Version (StructVersion value)
Byte 1: Flags (HeaderFlags combination)
Byte 2: Reserved
Byte 3: Reserved
[Optional: Field presence bitmap if HAS_OPTIONAL_FIELDS]
[Data fields]

Programmatic Usage¶

from pdc_struct.enums import HeaderFlags

# Check flags in received data
flags = data[1]
is_big_endian = bool(flags & HeaderFlags.BIG_ENDIAN)
has_optional = bool(flags & HeaderFlags.HAS_OPTIONAL_FIELDS)

# Combine flags
combined = HeaderFlags.BIG_ENDIAN | HeaderFlags.HAS_OPTIONAL_FIELDS

Enum Reference¶

`StructMode` ¶

Bases: Enum

Defines the serialization mode for struct packing.

Modes

C_COMPATIBLE: Fixed-size mode compatible with C structs. - Fixed struct size - No header metadata - Optional fields must have default values or factories - Null-terminated strings - Fixed-length buffers

DYNAMIC: Variable-size mode optimized for Python-to-Python communication. - Variable struct size - Includes header metadata - Supports optional fields - Variable-length strings

Source code in pdc_struct/enums.py

class StructMode(Enum):
    """Defines the serialization mode for struct packing.

    Modes:
        C_COMPATIBLE: Fixed-size mode compatible with C structs.
            - Fixed struct size
            - No header metadata
            - Optional fields must have default values or factories
            - Null-terminated strings
            - Fixed-length buffers

        DYNAMIC: Variable-size mode optimized for Python-to-Python communication.
            - Variable struct size
            - Includes header metadata
            - Supports optional fields
            - Variable-length strings
    """

    C_COMPATIBLE = "c_compatible"  # Fixed size, no header, no optional fields
    DYNAMIC = "dynamic"  # Variable size, header present, optional fields supported

`ByteOrder` ¶

Bases: Enum

Byte order (endianness) for multi-byte value serialization.

Controls how integers, floats, and other multi-byte values are arranged in memory. Each value corresponds to a Python struct module format character.

Attributes:

Name	Type	Description
`LITTLE_ENDIAN`		Least significant byte first. Used by x86, x64, and most ARM systems. Struct format: '<'.
`BIG_ENDIAN`		Most significant byte first. Also called "network byte order". Used by many network protocols. Struct format: '>'.
`NATIVE`		Use the system's native byte order. Not recommended for cross-platform data exchange. Struct format: '='.

Example

from pdc_struct import StructConfig, ByteOrder

For network protocols, use big-endian (network byte order)¶

config = StructConfig(byte_order=ByteOrder.BIG_ENDIAN)

For x86/x64 compatibility, use little-endian¶

config = StructConfig(byte_order=ByteOrder.LITTLE_ENDIAN)

Source code in pdc_struct/enums.py

class ByteOrder(Enum):
    """Byte order (endianness) for multi-byte value serialization.

    Controls how integers, floats, and other multi-byte values are arranged in memory.
    Each value corresponds to a Python struct module format character.

    Attributes:
        LITTLE_ENDIAN: Least significant byte first. Used by x86, x64, and most ARM
            systems. Struct format: '<'.
        BIG_ENDIAN: Most significant byte first. Also called "network byte order".
            Used by many network protocols. Struct format: '>'.
        NATIVE: Use the system's native byte order. Not recommended for cross-platform
            data exchange. Struct format: '='.

    Example:
        >>> from pdc_struct import StructConfig, ByteOrder
        >>>
        >>> # For network protocols, use big-endian (network byte order)
        >>> config = StructConfig(byte_order=ByteOrder.BIG_ENDIAN)
        >>>
        >>> # For x86/x64 compatibility, use little-endian
        >>> config = StructConfig(byte_order=ByteOrder.LITTLE_ENDIAN)
    """

    LITTLE_ENDIAN = "<"
    BIG_ENDIAN = ">"
    NATIVE = "="

`StructVersion` ¶

Bases: Enum

Version enum for struct format versioning

Source code in pdc_struct/enums.py

class StructVersion(Enum):
    """Version enum for struct format versioning"""

    V1 = 1

`HeaderFlags` ¶

Bases: IntFlag

Bit flags stored in byte 1 of DYNAMIC mode headers.

These flags describe properties of the serialized data, allowing the deserializer to correctly interpret the binary format. Multiple flags can be combined using bitwise OR.

The DYNAMIC mode header structure is

Byte 0: Version (StructVersion value) Byte 1: Flags (this enum) Byte 2: Reserved Byte 3: Reserved

Attributes:

Name	Type	Description
`LITTLE_ENDIAN`		Data uses little-endian byte ordering (0x00).
`BIG_ENDIAN`		Data uses big-endian byte ordering (0x01).
`HAS_OPTIONAL_FIELDS`		A field presence bitmap follows the header (0x02).

Example

from pdc_struct.enums import HeaderFlags

Check flags from raw header data¶

header = b'\x01\x03\x00\x00' # Version 1, big-endian with optional fields flags = header[1] bool(flags & HeaderFlags.BIG_ENDIAN) True bool(flags & HeaderFlags.HAS_OPTIONAL_FIELDS) True

Source code in pdc_struct/enums.py

class HeaderFlags(IntFlag):
    """Bit flags stored in byte 1 of DYNAMIC mode headers.

    These flags describe properties of the serialized data, allowing the deserializer
    to correctly interpret the binary format. Multiple flags can be combined using
    bitwise OR.

    The DYNAMIC mode header structure is:
        Byte 0: Version (StructVersion value)
        Byte 1: Flags (this enum)
        Byte 2: Reserved
        Byte 3: Reserved

    Attributes:
        LITTLE_ENDIAN: Data uses little-endian byte ordering (0x00).
        BIG_ENDIAN: Data uses big-endian byte ordering (0x01).
        HAS_OPTIONAL_FIELDS: A field presence bitmap follows the header (0x02).

    Example:
        >>> from pdc_struct.enums import HeaderFlags
        >>>
        >>> # Check flags from raw header data
        >>> header = b'\\x01\\x03\\x00\\x00'  # Version 1, big-endian with optional fields
        >>> flags = header[1]
        >>> bool(flags & HeaderFlags.BIG_ENDIAN)
        True
        >>> bool(flags & HeaderFlags.HAS_OPTIONAL_FIELDS)
        True
    """

    LITTLE_ENDIAN = 0x00
    BIG_ENDIAN = 0x01
    HAS_OPTIONAL_FIELDS = 0x02

Enums¶

StructMode¶

C_COMPATIBLE Mode¶

DYNAMIC Mode¶

ByteOrder¶

Usage Examples¶

Byte Order Visualization¶

StructVersion¶

HeaderFlags¶

Header Structure (DYNAMIC Mode)¶

Programmatic Usage¶

Enum Reference¶

StructMode ¶

ByteOrder ¶

For network protocols, use big-endian (network byte order)¶

For x86/x64 compatibility, use little-endian¶

StructVersion ¶

HeaderFlags ¶

Check flags from raw header data¶

See Also¶

`StructMode` ¶

`ByteOrder` ¶

`StructVersion` ¶

`HeaderFlags` ¶