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 enum34 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 – label (during building) or value (during parsing) cannot be translated, and no default was provided

Example:

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

import enum
class E(enum.IntEnum):
    one = 1
class F(enum.IntFlag):
    two = 2
Enum(Byte,      E, F) <--> Enum(Byte,      one=1, two=2)
FlagsEnum(Byte, E, F) <--> 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 enum34 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

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)
b'\x03'
>>> d.build("one|two")
b'\x03'
>>> d.build(1|2)
b'\x03'
>>> d.eight
'eight'
>>> d.one|d.two
'one|two'

import enum
class E(enum.IntEnum):
    one = 1
class F(enum.IntFlag):
    two = 2
Enum(Byte,      E, F) <--> Enum(Byte,      one=1, two=2)
FlagsEnum(Byte, E, F) <--> FlagsEnum(Byte, one=1, two=2)
construct.Mapping(subcon, mapping)

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

Parameters:
  • subcon – Construct instance
  • mapping – dict, for encoding (building) mapping

Example:

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