Integer flag to bytes and bytes to integer flag transform.
[plum.flag] Module Reference¶
The plum.flag
module provides the FlagX
transform which converts an
integer flags enumeration member into bytes and bytes into an integer flags
enumeration member. This reference page demonstrates creating and using a
FlagX
transform as well as provides API details.
The examples shown on this page require the following setup:
>>> from enum import IntFlag
>>> from plum.flag import FlagX
>>> from plum.utilities import pack, unpack
>>>
>>> class Color(IntFlag):
... RED = 1
... BLUE = 2
... GREEN = 4
... WHITE = RED | GREEN | BLUE
...
Basic Usage¶
The FlagX
transform accepts the following arguments:
enum: associated integer flag enumeration class nbytes: format size in bytes (any positive integer) byteorder: "big"
or"little"
(default)name: transform name (for representations including dump format column)
For example:
>>> color = FlagX(Color, nbytes=2, byteorder="big")
Use the transform to specify a format when using the pack()
and unpack()
utility
functions or when using other high level transforms. Its advantage over
using a IntX
transform is that unpacking results in the corresponding
integer flag enumeration member.
>>> fmt = [color, color]
>>>
>>> unpack(fmt, b'\x00\x01\x00\x06')
[<Color.RED: 1>, <Color.BLUE|GREEN: 6>]
>>>
>>> pack([Color.RED, Color.BLUE|Color.GREEN], fmt)
b'\x00\x01\x00\x06'
Tip
Use sys.byteorder
as the FlagX
transform byteorder
argument to
get the same byte order as the architecture of the machine your script
is running on.
API Reference¶
-
class
plum.flag.
FlagX
(enum: Type[enum.IntFlag], nbytes: int, byteorder: Union[Literal[little], Literal[big]] = 'little', name: Optional[str] = None)¶ Flag Enumeration to bytes and bytes to flag enumeration transform.
-
byteorder
¶ Byte order (“little” or “big”).
-
enum
¶ Integer flag enumeration.
-
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
-