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