Core API: Adapters and Validators

construct.ExprAdapter(subcon, decoder, encoder)

A generic adapter that takes encoder and decoder as parameters. You can use ExprAdapter instead of writing a full-blown class when only a simple lambda is needed.

Parameters:
  • subcon – Construct instance, subcon to adapt
  • encoder – lambda that takes (obj, context) and returns an encoded version of obj, or None for identity function
  • decoder – lambda that takes (obj, context) and returns an decoded version of obj, or None for identity function

Example:

# adds +1 to build values and subtracts -1 from parsed objects
ExprAdapter(Byte,
    encoder = lambda x,ctx: x+1,
    decoder = lambda x,ctx: x-1 )
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, or None for identity function

implement???

Example:

# unsets 4 out of 8 bits in parsed and build values
ExprSymmetricAdapter(Byte, encoder = lambda x,ctx: x & 0b00001111)
construct.ExprValidator(subcon, validator)

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

Parameters:
  • subcon – Construct instance, subcon to adapt
  • encoder – lambda that takes (obj, context) and returns a bool

Example:

ExprValidator(Byte, validator = lambda obj,ctx: obj in [1,3,5])
OneOf(Byte, [1,3,5])
construct.OneOf(subcon, valids)

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

Note

For performance, you should provide a set/frozenset but if items are not hashable, then a list would work the same, just slower.

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, you should provide a set/frozenset but if items are not hashable, then a list would work the same, just slower.

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:

example???
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:

example???