Core API: Bytes and bits

construct.Bytes(length)

Field consisting of a specified number of bytes.

Parses into a bytes (of given length). Builds into the stream directly (but checks that given object matches specified length). Can also build from an integer for convenience (although BytesInteger should be used instead). Size is the specified length.

Can also build from a bytearray.

Parameters:

length – integer or context lambda

Raises:

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

  • StringError – building from non-bytes value, perhaps unicode

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

Example:

>>> d = Bytes(4)
>>> d.parse(b'beef')
b'beef'
>>> d.build(b'beef')
b'beef'
>>> d.build(0)
b'\x00\x00\x00\x00'
>>> d.sizeof()
4

>>> d = Struct(
...     "length" / Int8ub,
...     "data" / Bytes(this.length),
... )
>>> d.parse(b"\x04beef")
Container(length=4, data=b'beef')
>>> d.sizeof()
construct.core.SizeofError: cannot calculate size, key not found in context
construct.GreedyBytes()

Field consisting of unknown number of bytes.

Parses the stream to the end. Builds into the stream directly (without checks). Size is undefined.

Can also build from a bytearray.

Raises:

  • StreamError – stream failed when reading until EOF

  • StringError – building from non-bytes value, perhaps unicode

Example:

>>> GreedyBytes.parse(b"asislight")
b'asislight'
>>> GreedyBytes.build(b"asislight")
b'asislight'
construct.setGlobalPrintFullStrings(enabled=False)

When enabled, Container __str__ produces full content of bytes and unicode strings, otherwise and by default, it produces truncated output (16 bytes and 32 characters).

Parameters:

enabled – bool

construct.Bitwise(subcon)

Converts the stream from bytes to bits, and passes the bitstream to underlying subcon. Bitstream is a stream that contains 8 times as many bytes, and each byte is either \x00 or \x01 (in documentation those bytes are called bits).

Parsing building and size are deferred to subcon, although size gets divided by 8 (therefore the subcon’s size must be a multiple of 8).

Note that by default the bit ordering is from MSB to LSB for every byte (ie. bit-level big-endian). If you need it reversed, wrap this subcon with construct.core.BitsSwapped.

Parameters:

subcon – Construct instance, any field that works with bits (like BitsInteger) or is bit-byte agnostic (like Struct or Flag)

See Transformed and Restreamed for raisable exceptions.

Example:

>>> d = Bitwise(Struct(
...     'a' / Nibble,
...     'b' / Bytewise(Float32b),
...     'c' / Padding(4),
... ))
>>> d.parse(bytes(5))
Container(a=0, b=0.0, c=None)
>>> d.sizeof()
5

Obtaining other byte or bit orderings:

>>> d = Bitwise(Bytes(16))
>>> d.parse(b'\x01\x03')
b'\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x01\x01'
>>> d = BitsSwapped(Bitwise(Bytes(16)))
>>> d.parse(b'\x01\x03')
b'\x01\x00\x00\x00\x00\x00\x00\x00\x01\x01\x00\x00\x00\x00\x00\x00'
construct.Bytewise(subcon)

Converts the bitstream back to normal byte stream. Must be used within Bitwise.

Parsing building and size are deferred to subcon, although size gets multiplied by 8.

Parameters:

subcon – Construct instance, any field that works with bytes or is bit-byte agnostic

See Transformed and Restreamed for raisable exceptions.

Example:

>>> d = Bitwise(Struct(
...     'a' / Nibble,
...     'b' / Bytewise(Float32b),
...     'c' / Padding(4),
... ))
>>> d.parse(bytes(5))
Container(a=0, b=0.0, c=None)
>>> d.sizeof()
5