structclasses

This is a library for working with binary data protocols. Building upon dataclasses from the Python standard library, as well as taking inspiration for the API design from the Ruby gem bindata.

The result is a augmented dataclass object with to/from binary serialization capabilities.

install

pip install structclasses

example

from structclasses import structclass, uint8, union, text, binary, field


@structclass
class DemoHeader:
  example_id: int  # alias for `int32`


@structclass
class Demo:
  field_a: uint8
  header: DemoHeader
  msg: text[32]     # The length may reference a previously defined field for dynamic length objects.
  payload: union[
    ("number", uint8),
    ("data", binary[8])
  ] = field(
    selector="field_a",  # The value of the named field specifies the union type to use. (May be a callable instead for more flexibility.)
    field_selector_map={
      "number": 0,       # When `field_a` is 0, `payload` is a `uint8`.
      "data": 1,         # When `field_a` is 1, `payload` is a `binary[8]`.
    })

demo = Demo(field_a=0, msg="hello world", header=DemoHeader(123), payload={"number": 42})

packed_binary = demo._pack()  # => b'\x00\x00\x00\x00{\x00\x00\x00hello world\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00*'
Demo._unpack(packed_binary) == demo  # => True

A structclass works as a drop-in substitute for the dataclass decorator, only adding the _pack()/_unpack() methods to the class for serializing to/from binary data.

Metadata

Release files for structclasses 0.30

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for structclasses 0.30
File	Interpreter	ABI	Platform	Reset
structclasses-0.30-py3-none-any.whl 20.1 kB Apr 10, 2025	Python 3	none	any	Details

Release files / structclasses-0.30-py3-none-any.whl

Download URL	structclasses-0.30-py3-none-any.whl
Size	20.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c97408219285a316e43d06e1c9849a87b1e7f2925cc6367bad8b1bfd27d80e5e`
BLAKE2b-256 checksum How to use checksums	`6932f329b9d853bd98874f88ef868f3745b73982d26df8cd3bdade7776381d14`
Upload date	Apr 10, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.10.13`