Core API: Integers and Floats

construct.FormatField(endianity, format)

Field that uses struct module to pack and unpack CPU-sized integers and floats. This is used to implement most Int* Float* fields, but for example cannot pack 24-bit integers, which is left to BytesInteger class.

See struct module documentation for instructions on crafting format strings.

Parses into an integer. Builds from an integer into specified byte count and endianness. Size is determined by struct module according to specified format string.

Parameters:
  • endianity – string, character like: < > =
  • format – string, character like: f d B H L Q b h l q
Raises:
  • StreamError – requested reading negative amount, could not read enough bytes, requested writing different amount than actual data, or could not write all bytes
  • FormatFieldError – wrong format string, or struct.(un)pack complained about the value

Example:

>>> d = FormatField(">", "H") or Int16ub
>>> d.parse(b"\x01\x00")
256
>>> d.build(256)
b"\x01\x00"
>>> d.sizeof()
2
construct.BytesInteger(length, signed=False, swapped=False)

Field that packs arbitrarily large integers. Some Int24* fields use this class.

Parses into an integer. Builds from an integer into specified byte count and endianness. Size is specified in ctor.

Analog to BitsInteger that operates on bits. In fact, BytesInteger(n) is equivalent to Bitwise(BitsInteger(8*n)) and BitsInteger(n) is equivalent to Bytewise(BytesInteger(n//8))) .

Parameters:
  • length – integer or context lambda, number of bytes in the field
  • signed – bool, whether the value is signed (two’s complement), default is False (unsigned)
  • swapped – bool, whether to swap byte order (little endian), default is False (big endian)
Raises:
  • StreamError – requested reading negative amount, could not read enough bytes, requested writing different amount than actual data, or could not write all bytes
  • IntegerError – lenght is negative, given a negative value when field is not signed, or not an integer

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

Example:

>>> d = BytesInteger(4) or Int32ub
>>> d.parse(b"abcd")
1633837924
>>> d.build(1)
b'\x00\x00\x00\x01'
>>> d.sizeof()
4
construct.BitsInteger(length, signed=False, swapped=False)

Field that packs arbitrarily large (or small) integers. Some fields (Bit Nibble Octet) use this class. Must be enclosed in Bitwise context.

Parses into an integer. Builds from an integer into specified bit count and endianness. Size (in bits) is specified in ctor.

Note that little-endianness is only defined for multiples of 8 bits.

Analog to BytesInteger that operates on bytes. In fact, BytesInteger(n) is equivalent to Bitwise(BitsInteger(8*n)) and BitsInteger(n) is equivalent to Bytewise(BytesInteger(n//8))) .

Parameters:
  • length – integer or context lambda, number of bits in the field
  • signed – bool, whether the value is signed (two’s complement), default is False (unsigned)
  • swapped – bool, whether to swap byte order (little endian), default is False (big endian)
Raises:
  • StreamError – requested reading negative amount, could not read enough bytes, requested writing different amount than actual data, or could not write all bytes
  • IntegerError – lenght is negative, given a negative value when field is not signed, or not an integer

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

Example:

>>> d = Bitwise(BitsInteger(8)) or Bitwise(Octet)
>>> d.parse(b"\x10")
16
>>> d.build(255)
b'\xff'
>>> d.sizeof()
1
construct.VarInt()

VarInt encoded integer. Each 7 bits of the number are encoded in one byte of the stream, where leftmost bit (MSB) is unset when byte is terminal. Scheme is defined at Google site related to Protocol Buffers.

Can only encode non-negative numbers.

Parses into an integer. Builds from an integer. Size is undefined.

Raises:
  • StreamError – requested reading negative amount, could not read enough bytes, requested writing different amount than actual data, or could not write all bytes
  • IntegerError – given a negative value, or not an integer

Example:

>>> VarInt.build(1)
b'\x01'
>>> VarInt.build(2**100)
b'\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x04'