Core API: Structs and Sequences

construct.Struct(*subcons, **kw)

Sequence of usually named constructs, similar to structs in C. The elements are parsed and built in the order they are defined. If a member is anonymous (its name is None) then it gets parsed and its value discarded, or it gets build from nothing (from None).

Some fields do not need to be named, since they are built without value anyway. See Const Padding Pass Terminated for examples of such fields.

Size is the sum of all subcon sizes, unless any subcon raises SizeofError.

Operator + can also be used to make Structs.

See also

Can be nested easily, and embedded using Embedded() wrapper that merges members with parent’s members.

Parameters:subcons – subcons that make up this structure, some can be anonymous

Example:

>>> d = Struct("a"/Int8ul, "data"/Bytes(2), "data2"/Bytes(this.a))
>>> d.parse(b"\x01abc")
Container(a=1)(data=b'ab')(data2=b'c')
>>> d.build(_)
b'\x01abc'
>>> d.build(dict(a=5, data=b"??", data2=b"hello"))
b'\x05??hello'

>>> d = Struct(Const(b"MZ"), Padding(2), Pass, Terminated)
>>> d.build({})
b'MZ\x00\x00'
>>> d.parse(_)
Container()
>>> d.sizeof()
4

Alternative syntax (not recommended):
>>> ("a"/Byte + "b"/Byte + "c"/Byte + "d"/Byte)

Alternative syntax, note this works ONLY on python 3.6+:
>>> Struct(a=Byte, b=Byte, c=Byte, d=Byte)
construct.Sequence(*subcons, **kw)

Sequence of unnamed constructs. The elements are parsed and built in the order they are defined. If a member is named, its parsed value gets inserted into the context. This allows using members that refer to previous members values.

Size is the sum of all subcon sizes, unless any subcon raises SizeofError.

Operator >> can also be used to make Sequences.

See also

Can be nested easily, and embedded using Embedded() wrapper that merges entries with parent’s entries.

Parameters:subcons – subcons that make up this sequence, some can be named

Example:

>>> d = (Byte >> Byte)
>>> d.parse(b'\x01\x02')
[1, 2]
>>> d.build([1, 2])
b'\x01\x02'
>>> d.sizeof()
2

>>> d = Sequence(Byte, CString(), Float32b)
>>> d.build([255, b"hello", 123.0])
b'\xffhello\x00B\xf6\x00\x00'
>>> d.parse(_)
[255, b'hello', 123.0]

Alternative syntax (not recommended):
>>> (Byte >> "Byte >> "c"/Byte >> "d"/Byte)

Alternative syntax, note this works ONLY on python 3.6+:
>>> Sequence(a=Byte, b=Byte, c=Byte, d=Byte)
construct.Embedded(subcon)

Embeds a struct into the enclosing struct, merging fields. Can also embed sequences into sequences, merging items. Name is inherited from subcon.

Warning

You can use Embedded(Switch(…)) but not Switch(Embedded(…)). Sames applies to If and IfThenElse macros.

Parameters:subcon – the inner struct to embed inside outer struct or sequence

Example:

>>> d = Struct("a"/Byte, Embedded(Struct("b"/Byte)), "c"/Byte)
>>> d.parse(b"abc")
Container(a=97)(b=98)(c=99)
construct.AlignedStruct(modulus, *subcons, **kw)

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

See also

Uses Aligned() and Struct().

Parameters:
  • modulus – passed to each member
  • *subcons – subcons that make up the Struct
  • **kw – named subcons, extend the Struct

Example:

>>> d = AlignedStruct(4, "a"/Int8ub, "b"/Int16ub)
>>> d.build(dict(a=1,b=5))
b'\x01\x00\x00\x00\x00\x05\x00\x00'
>>> d.parse(_)
Container(a=1)(b=5)
>>> d.sizeof()
8
construct.BitStruct(*subcons)

Makes a structure inside a Bitwise.

See also

Uses Bitwise() and Struct().

Parameters:*subcons – the subcons that make up this structure

Example:

>>> d = BitStruct(
...     "a" / Flag,
...     "b" / Nibble,
...     "c" / BitsInteger(10),
...     "d" / Padding(1),
... )
>>> d.parse(b"\xbe\xef")
Container(a=True)(b=7)(c=887)(d=None)
>>> d.sizeof()
2
construct.EmbeddedBitStruct(*subcons)

Makes an embedded BitStruct.

See also

Uses Bitwise() and Embedded() and Struct().

Parameters:*subcons – the subcons that make up this structure

Example:

EmbeddedBitStruct  <-->  Bitwise(Embedded(Struct(...)))