Metadata-Version: 2.4
Name: structclasses
Version: 0.27
Summary: Boost your `dataclass` objects with suport for binary serialization.
Author-email: Andreas Stenius <andreas.stenius@gmail.com>
Requires-Python: >=3.10,<3.13
Description-Content-Type: text/markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
Requires-Dist: typing_extensions
Project-URL: Repository, https://github.com/kaos/structclasses

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](https://rubygems.org/gems/bindata).

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

install
-------

    pip install structclasses
    
example
-------

```python
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.


