Core API: Adapters and Validators

construct.ExprAdapter(subcon, decoder, encoder)

Generic adapter that takes decoder and encoder lambdas as parameters. You can use ExprAdapter instead of writing a full-blown class deriving from Adapter when only a simple lambda is needed.

Parameters:

• subcon – Construct instance, subcon to adapt

• decoder – lambda that takes (obj, context) and returns an decoded version of obj

• encoder – lambda that takes (obj, context) and returns an encoded version of obj

Example:

>>> d = ExprAdapter(Byte, obj_+1, obj_-1)
>>> d.parse(b'\x04')
5
>>> d.build(5)
b'\x04'

construct.ExprSymmetricAdapter(subcon, encoder)

Macro around ExprAdapter.

Parameters:

• subcon – Construct instance, subcon to adapt

• encoder – lambda that takes (obj, context) and returns both encoded version and decoded version of obj

Example:

>>> d = ExprSymmetricAdapter(Byte, obj_ & 0b00001111)
>>> d.parse(b"ÿ")
15
>>> d.build(255)
b''

construct.ExprValidator(subcon, validator)

Generic adapter that takes validator lambda as parameter. You can use ExprValidator instead of writing a full-blown class deriving from Validator when only a simple lambda is needed.

Parameters:

• subcon – Construct instance, subcon to adapt

• validator – lambda that takes (obj, context) and returns a bool

Example:

>>> d = ExprValidator(Byte, obj_ & 0b11111110 == 0)
>>> d.build(1)
b'\x01'
>>> d.build(88)
ValidationError: object failed validation: 88

construct.OneOf(subcon, valids)

Validates that the object is one of the listed values, both during parsing and building.

Note

For performance, valids should be a set or frozenset.

Parameters:

• subcon – Construct instance, subcon to validate

• valids – collection implementing __contains__, usually a list or set

Raises:

ValidationError – parsed or build value is not among valids

Example:

>>> d = OneOf(Byte, [1,2,3])
>>> d.parse(b"\x01")
1
>>> d.parse(b"\xff")
construct.core.ValidationError: object failed validation: 255

construct.NoneOf(subcon, invalids)

Validates that the object is none of the listed values, both during parsing and building.

Note

For performance, valids should be a set or frozenset.

Parameters:

• subcon – Construct instance, subcon to validate

• invalids – collection implementing __contains__, usually a list or set

Raises:

ValidationError – parsed or build value is among invalids

construct.Filter(predicate, subcon)

Filters a list leaving only the elements that passed through the predicate.

Parameters:

• subcon – Construct instance, usually Array GreedyRange Sequence

• predicate – lambda that takes (obj, context) and returns a bool

Can propagate any exception from the lambda, possibly non-ConstructError.

Example:

>>> d = Filter(obj_ != 0, Byte[:])
>>> d.parse(b"\x00\x02\x00")
[2]
>>> d.build([0,1,0,2,0])
b'\x01\x02'

construct.Slicing(subcon, count, start, stop, step=1, empty=None)

Adapter for slicing a list. Works with GreedyRange and Sequence.

Parameters:

• subcon – Construct instance, subcon to slice

• count – integer, expected number of elements, needed during building

• start – integer for start index (or None for entire list)

• stop – integer for stop index (or None for up-to-end)

• step – integer, step (or 1 for every element)

• empty – object, value to fill the list with, during building

Example:

d = Slicing(Array(4,Byte), 4, 1, 3, empty=0)
assert d.parse(b"\x01\x02\x03\x04") == [2,3]
assert d.build([2,3]) == b"\x00\x02\x03\x00"
assert d.sizeof() == 4

construct.Indexing(subcon, count, index, empty=None)

Adapter for indexing a list (getting a single item from that list). Works with Range and Sequence and their lazy equivalents.

Parameters:

• subcon – Construct instance, subcon to index

• count – integer, expected number of elements, needed during building

• index – integer, index of the list to get

• empty – object, value to fill the list with, during building

Example:

d = Indexing(Array(4,Byte), 4, 2, empty=0)
assert d.parse(b"\x01\x02\x03\x04") == 3
assert d.build(3) == b"\x00\x00\x03\x00"
assert d.sizeof() == 4