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
-