None to no bytes and no bytes to None transform.

[plum.none] Module Reference

The plum.none module provides the NoneX transform for converting None into no bytes and no bytes into None. This reference page demonstrates creating and using the NoneX transform with a typical use case as well as provides API details.

The examples shown on this page require the following setup:

>>> from plum.int import IntX
>>> from plum.none import NoneX
>>> from plum.structure import Structure, member
>>>
>>> uint8 = IntX(nbytes=1, byteorder="little", signed=False)
>>> uint16 = IntX(nbytes=2, byteorder="little", signed=False)

Basic Use

The NoneX transform accepts the following argument:

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

For example:

>>> nil = NoneX()

One application where NoneX may become necessary is when a structure member’s datatype depends on another structure member. The variably typed member as shown in the following example demonstrates a use case. The data member’s type depends on the value of the datatype member as defined by the type mapping. When datatype equals 0, no bytes are expected for the data member. When datatype equals 1 or 2, bytes for a uint8 or uint16 (respectively) are expected for the data member:

>>> class Struct(Structure):
...     datatype: int = member(fmt=uint8)
...     data: object = member(fmt={0: nil, 1: uint8, 2: uint16}.__getitem__, fmt_arg=datatype)
...
>>> Struct.unpack(b'\x00').dump()
+--------+----------+-------+-------+--------------------+
| Offset | Access   | Value | Bytes | Format             |
+--------+----------+-------+-------+--------------------+
|        |          |       |       | Struct (Structure) |
| 0      | datatype | 0     | 00    | uint8              |
|        | data     | None  |       | None               |
+--------+----------+-------+-------+--------------------+
>>>
>>> Struct.unpack(b'\x01\x02').dump()
+--------+----------+-------+-------+--------------------+
| Offset | Access   | Value | Bytes | Format             |
+--------+----------+-------+-------+--------------------+
|        |          |       |       | Struct (Structure) |
| 0      | datatype | 1     | 01    | uint8              |
| 1      | data     | 2     | 02    | uint8              |
+--------+----------+-------+-------+--------------------+
>>>
>>> buffer, dump = Struct(datatype=0, data=None).ipack_and_dump()
>>> buffer
b'\x00'
>>> print(dump)
+--------+----------+-------+-------+--------------------+
| Offset | Access   | Value | Bytes | Format             |
+--------+----------+-------+-------+--------------------+
|        |          |       |       | Struct (Structure) |
| 0      | datatype | 0     | 00    | uint8              |
|        | data     | None  |       | None               |
+--------+----------+-------+-------+--------------------+

API Reference

class plum.none.NoneX(name: str = 'None')

None to no bytes and no bytes to None transform.

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