Core API: Structs and Sequences

construct.Struct(*subcons, **kw)

A sequence of usually named constructs, similar to structs in C. The elements are parsed and built in the order they are defined.

Some fields do not need to be named, since they are built from None anyway. See Const Padding Pass Terminated.

See also

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

Parameters:subcons – a sequence of subconstructs that make up this structure

Example:

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

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

Note that this syntax works ONLY on python 3.6 and pypy due to unordered keyword arguments:
>>> Struct(a=Byte, b=Byte, c=Byte, d=Byte)
construct.Sequence(*subcons, **kw)

A sequence of unnamed constructs. The elements are parsed and built in the order they are defined.

See also

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

Parameters:subcons – a sequence of subconstructs that make up this sequence

Example:

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

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

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

Parameters:subcon – the struct to embed

Example:

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

Makes a structure where each field is aligned to the same modulus.

See also

Uses Aligned() and ~construct.core.Struct.

Parameters:
  • modulus – passed to each member
  • *subcons – the subcons that make up this structure
  • pattern – optional, keyword parameter passed to each member

Example:

>>> AlignedStruct(4, "a"/Int8ub, "b"/Int16ub).build(dict(a=1,b=5))
b'\x01\x00\x00\x00\x00\x05\x00\x00'
>>> AlignedStruct(4, "a"/Int8ub, "b"/Int16ub).parse(_)
Container(a=1)(b=5)
>>> AlignedStruct(4, "a"/Int8ub, "b"/Int16ub).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:

>>> BitStruct("field"/Octet).build(dict(field=5))
b'\x05'
>>> BitStruct("field"/Octet).parse(_)
Container(field=5)
>>> BitStruct("field"/Octet).sizeof()
1

>>> format = BitStruct(
...     "a" / Flag,
...     "b" / Nibble,
...     "c" / BitsInteger(10),
...     "d" / Padding(1),
... )
>>> format.parse(b"\xbe\xef")
Container(a=True)(b=7)(c=887)(d=None)
>>> format.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