Transform dict/iterable values to bytes and vice versa.

[plum.items] Module Reference

The plum.items module provides the ItemsX transform which converts objects as specified by a format into bytes and vice versa. This reference page shows how to create and use an ItemsX transform for packing and unpacking bytes, a lighter weight method than a custom Structure subclass. This page also provides API details.

The examples shown on this page require the following setup:

>>> from plum.array import ArrayX
>>> from plum.littleendian import uint8
>>> from plum.items import ItemsX
>>> from plum.utilities import pack, unpack

Basic Usage

The ItemsX transform accepts the following arguments:

fmt:transform format
name:transform name (for representations including dump format column)

The ItemsX transform fmt argument accepts a transform or any dictionary, list, or tuple of transforms (all the variations described in the Arbitrary Format tutorial).

When packing, the items transform accepts values and converts them into a bytes sequence per the fmt:

>>> fmt = ItemsX(fmt=(uint8, uint8))
>>> buffer = pack([0, 1], fmt)
>>> buffer
b'\x00\x01'

When unpacking, the items transform produces values from the bytes sequence per the fmt:

>>> unpack(fmt, buffer)
(0, 1)

But you could just as easily pass [uint8, uint16] as the format into the pack() and unpack() utility methods. Wrapping a format in an ItemsX instance becomes necessary when specifying it as the fmt argument of an ArrayX or Structure member. For example:

>>> fmt = ArrayX(fmt=ItemsX(fmt=(uint8, uint8)), dims=(2,))
>>>
>>> buffer = pack([(0, 1), (2, 3)], fmt)
>>> buffer
b'\x00\x01\x02\x03'
>>> unpack(fmt, buffer)
[(0, 1), (2, 3)]

API Reference

class plum.items.ItemsX(fmt: Union[Dict[str, Any], List[Any], plum.transform.Transform, Tuple[Any, ...], Type[plum.data.Data], None] = None, name: Optional[str] = None, hint: Optional[str] = None)

Value to bytes and bytes to value transformer.

fmt

Items format.

name

Transform format name (for repr and dump “Format” column).

nbytes

Transform format size in bytes.

pack(value: Any) → bytes

Pack value as formatted bytes.

Raises:PackError if type error, value error, etc.
pack_and_dump(value: Any) → Tuple[bytes, plum.dump.Dump]

Pack value as formatted bytes and produce bytes summary.

Raises:PackError if type error, value error, etc.
unpack(buffer: bytes) → Any

Unpack value from formatted bytes.

Raises:UnpackError if insufficient bytes, excess bytes, or value error
unpack_and_dump(buffer: bytes) → Tuple[Any, plum.dump.Dump]

Unpack value from bytes and produce packed bytes summary.

Raises:UnpackError if insufficient bytes, excess bytes, or value error