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.
- 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()
andEmbedded()
andStruct()
.- Parameters
*subcons – the subcons that make up this structure