Core API: Alignment and Padding

construct.Padding(length, pattern=b'\x00')

Appends null bytes.

Parsing consumes specified amount of bytes and discards it. Building writes specified pattern byte multiplied into specified length. Size is same as specified.

Parameters:

  • length – integer or context lambda, length of the padding

  • pattern – b-character, padding pattern, default is \x00

Raises:

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

  • PaddingError – length was negative

  • PaddingError – pattern was not bytes (b-character)

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

Example:

>>> d = Padding(4) or Padded(4, Pass)
>>> d.build(None)
b'\x00\x00\x00\x00'
>>> d.parse(b"****")
None
>>> d.sizeof()
4
construct.Padded(length, subcon, pattern=b'\x00')

Appends additional null bytes to achieve a length.

Parsing first parses the subcon, then uses stream.tell() to measure how many bytes were read and consumes additional bytes accordingly. Building first builds the subcon, then uses stream.tell() to measure how many bytes were written and produces additional bytes accordingly. Size is same as length, but negative amount results in error. Note that subcon can actually be variable size, it is the eventual amount of bytes that is read or written during parsing or building that determines actual padding.

Parameters:

  • length – integer or context lambda, length of the padding

  • subcon – Construct instance

  • pattern – optional, b-character, padding pattern, default is \x00

Raises:

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

  • PaddingError – length is negative

  • PaddingError – subcon read or written more than the length (would cause negative pad)

  • PaddingError – pattern is not bytes of length 1

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

Example:

>>> d = Padded(4, Byte)
>>> d.build(255)
b'\xff\x00\x00\x00'
>>> d.parse(_)
255
>>> d.sizeof()
4

>>> d = Padded(4, VarInt)
>>> d.build(1)
b'\x01\x00\x00\x00'
>>> d.build(70000)
b'\xf0\xa2\x04\x00'
construct.Aligned(modulus, subcon, pattern=b'\x00')

Appends additional null bytes to achieve a length that is shortest multiple of a modulus.

Note that subcon can actually be variable size, it is the eventual amount of bytes that is read or written during parsing or building that determines actual padding.

Parsing first parses subcon, then consumes an amount of bytes to sum up to specified length, and discards it. Building first builds subcon, then writes specified pattern byte to sum up to specified length. Size is subcon size plus modulo remainder, unless SizeofError was raised.

Parameters:

  • modulus – integer or context lambda, modulus to final length

  • subcon – Construct instance

  • pattern – optional, b-character, padding pattern, default is \x00

Raises:

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

  • PaddingError – modulus was less than 2

  • PaddingError – pattern was not bytes (b-character)

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

Example:

>>> d = Aligned(4, Int16ub)
>>> d.parse(b'\x00\x01\x00\x00')
1
>>> d.sizeof()
4
construct.AlignedStruct(modulus, *subcons, **subconskw)

Makes a structure where each field is aligned to the same modulus (it is a struct of aligned fields, NOT an aligned struct).

See Aligned and Struct for semantics and raisable exceptions.

Parameters:

  • modulus – integer or context lambda, passed to each member

  • *subcons – Construct instances, list of members, some can be anonymous

  • **subconskw – Construct instances, list of members (requires Python 3.6)

Example:

>>> d = AlignedStruct(4, "a"/Int8ub, "b"/Int16ub)
>>> d.build(dict(a=0xFF,b=0xFFFF))
b'\xff\x00\x00\x00\xff\xff\x00\x00'