Core API: Mappings

construct.Flag()

One byte (or one bit) field that maps to True or False. Other non-zero bytes are also considered True. Size is defined as 1.

Raises:

StreamError – requested reading negative amount, could not read enough bytes, requested writing different amount than actual data, or could not write all bytes

Example:

>>> Flag.parse(b"\x01")
True
>>> Flag.build(True)
b'\x01'

construct.Enum(subcon, *merge, **mapping)

Translates unicode label names to subcon values, and vice versa.

Parses integer subcon, then uses that value to lookup mapping dictionary. Returns an integer-convertible string (if mapping found) or an integer (otherwise). Building is a reversed process. Can build from an integer flag or string label. Size is same as subcon, unless it raises SizeofError.

There is no default parameter, because if no mapping is found, it parses into an integer without error.

This class supports enum module. See examples.

This class supports exposing member labels as attributes, as integer-convertible strings. See examples.

Parameters:

• subcon – Construct instance, subcon to map to/from

• *merge – optional, list of enum.IntEnum and enum.IntFlag instances, to merge labels and values from

• **mapping – dict, mapping string names to values

Raises:

MappingError – building from string but no mapping found

Example:

>>> d = Enum(Byte, one=1, two=2, four=4, eight=8)
>>> d.parse(b"\x01")
'one'
>>> int(d.parse(b"\x01"))
1
>>> d.parse(b"\xff")
255
>>> int(d.parse(b"\xff"))
255

>>> d.build(d.one or "one" or 1)
b'\x01'
>>> d.one
'one'

import enum
class E(enum.IntEnum or enum.IntFlag):
    one = 1
    two = 2

Enum(Byte, E) <--> Enum(Byte, one=1, two=2)
FlagsEnum(Byte, E) <--> FlagsEnum(Byte, one=1, two=2)

construct.FlagsEnum(subcon, *merge, **flags)

Translates unicode label names to subcon integer (sub)values, and vice versa.

Parses integer subcon, then creates a Container, where flags define each key. Builds from a container by bitwise-oring of each flag if it matches a set key. Can build from an integer flag or string label directly, as well as | concatenations thereof (see examples). Size is same as subcon, unless it raises SizeofError.

This class supports enum module. See examples.

This class supports exposing member labels as attributes, as bitwisable strings. See examples.

Parameters:

• subcon – Construct instance, must operate on integers

• *merge – optional, list of enum.IntEnum and enum.IntFlag instances, to merge labels and values from

• **flags – dict, mapping string names to integer values

Raises:

• MappingError – building from object not like: integer string dict

• MappingError – building from string but no mapping found

Can raise arbitrary exceptions when computing | and & and value is non-integer.

Example:

>>> d = FlagsEnum(Byte, one=1, two=2, four=4, eight=8)
>>> d.parse(b"\x03")
Container(one=True, two=True, four=False, eight=False)
>>> d.build(dict(one=True,two=True))
b'\x03'

>>> d.build(d.one|d.two or "one|two" or 1|2)
b'\x03'

import enum
class E(enum.IntEnum or enum.IntFlag):
    one = 1
    two = 2

Enum(Byte, E) <--> Enum(Byte, one=1, two=2)
FlagsEnum(Byte, E) <--> FlagsEnum(Byte, one=1, two=2)

construct.setGlobalPrintFalseFlags(enabled=False)

When enabled, Container __str__ that was produced by FlagsEnum parsing prints all values, otherwise and by default, it prints only the values that are True.

Parameters:

enabled – bool

construct.Mapping(subcon, mapping)

Adapter that maps objects to other objects. Translates objects after parsing and before building. Can for example, be used to translate between enum objects and strings, but Enum class supports enum module already and is recommended.

Parameters:

• subcon – Construct instance

• mapping – dict, for encoding (building) mapping, the reversed is used for parsing mapping

Raises:

MappingError – parsing or building but no mapping found

Example:

>>> x = object
>>> d = Mapping(Byte, {x:0})
>>> d.parse(b"\x00")
x
>>> d.build(x)
b'\x00'