Quick Reference#

This section gives a summary of the bitstring module’s classes, functions and attributes.

The main classes are:

  • Bits – An efficient, immutable container of bits.

  • BitArray – A mutable version of Bits that can be changed after creation.

  • Reader – Wraps a Bits or BitArray with a bit position, for sequential reading and parsing.

  • Array – A mutable, list-like container whose items all share the same fixed-length binary format.

  • Dtype – A data type describing how to pack, unpack and present a bit interpretation.

Bits#

Bits is the most basic class and is just a container of bits. It is immutable, so once created its value cannot change.

Bits(auto, /, *, length: int | None = None, **kwargs)

The first parameter (usually referred to as auto) is most often a parsable string, a bytes-like object, or another bitstring. For zero-filled, bool-iterable, joined or file-based construction prefer the explicit factory methods below.

A single initialiser from kwargs can be used instead of auto, including bin, hex, oct, bool, u, i and f.

Examples:

Bits('0xef')
Bits(f=-50.5, length=32)
Bits('u10=99')
Bits(u=99, length=10)

Methods#

  • all – Check if all specified bits are set to 1 or 0.

  • any – Check if any of specified bits are set to 1 or 0.

  • copy – Return a copy of the bitstring.

  • count – Count the number of bits set to 1 or 0.

  • cut – Create generator of constant sized chunks.

  • endswith – Return whether the bitstring ends with a sub-bitstring.

  • find – Find a sub-bitstring in the current bitstring.

  • findall – Find all occurrences of a sub-bitstring in the current bitstring.

  • from_bools – Create a bitstring from an iterable of bool-like values.

  • from_bytes – Create a bitstring from bytes-like data.

  • from_dtype – Create a bitstring by packing a value according to a dtype.

  • from_file – Create a bitstring from a file path or binary file object.

  • from_joined – Create a bitstring by concatenating a sequence.

  • from_ones – Create a bitstring of one bits.

  • from_string – Create a bitstring from a formatted string.

  • from_tibs – Create a bitstring from a tibs.Tibs or tibs.Mutibs instance.

  • from_zeros – Create a bitstring of zero bits.

  • join – Join bitstrings together using current bitstring.

  • pp – Pretty print the bitstring.

  • rfind – Seek backwards to find a sub-bitstring.

  • split – Create generator of chunks split by a delimiter.

  • startswith – Return whether the bitstring starts with a sub-bitstring.

  • to_immutable – Return the bitstring as an immutable Bits.

  • to_mutable – Return the bitstring as a mutable BitArray.

  • to_bools – Return bitstring as a list of bools.

  • to_bytes – Return bitstring as bytes, padding if needed.

  • to_file – Write bitstring to file, padding if needed.

  • to_tibs – Return the data as a tibs.Tibs instance.

  • unpack – Interpret bits using format string.

Special methods#

Also available are operators that will return a new bitstring (or check for equality):

  • == / != – Equality tests.

  • [] – Get an element or slice.

  • for – Iterate over the bits as bools.

  • + – Concatenate with another bitstring.

  • * – Concatenate multiple copies of the current bitstring.

  • ~ – Invert every bit of the bitstring.

  • << – Shift bits to the left.

  • >> – Shift bits to the right.

  • & – Bit-wise AND between two bitstrings.

  • | – Bit-wise OR between two bitstrings.

  • ^ – Bit-wise XOR between two bitstrings.

Properties#

These read-only properties of the Bits object are interpretations of the binary data and are calculated as required. Many require the bitstring to be specific lengths.

  • bin – The bitstring as a binary string.

  • bool – For single bit bitstrings, interpret as True or False.

  • bytes – The bitstring as a bytes object.

  • f / float / fbe – Interpret as a big-endian floating point number.

  • fle – Interpret as a little-endian floating point number.

  • hex – The bitstring as a hexadecimal string.

  • i / int – Interpret as a two’s complement signed integer.

  • ibe – Interpret as a big-endian signed integer.

  • ile – Interpret as a little-endian signed integer.

  • oct – The bitstring as an octal string.

  • u / uint – Interpret as a two’s complement unsigned integer.

  • ube – Interpret as a big-endian unsigned integer.

  • ule – Interpret as a little-endian unsigned integer.

There are also various other flavours of 16-bit, 8-bit and smaller floating point types (see Exotic Floating Point Formats) and exponential-Golomb integer types (see Exponential-Golomb Codes) that are not listed here for brevity.

BitArray#

Bits ⟶ BitArray

BitArray adds mutating methods to Bits. The constructor is the same as for Bits.

Additional methods#

All of the methods listed above for the Bits class are available, plus:

  • append – Append a bitstring.

  • byteswap – Change byte endianness in-place.

  • clear – Remove all bits from the bitstring.

  • insert – Insert a bitstring.

  • invert – Flip bit(s) between one and zero.

  • overwrite – Overwrite a section with a new bitstring.

  • prepend – Prepend a bitstring.

  • replace – Replace occurrences of one bitstring with another.

  • reverse – Reverse bits in-place.

  • rol – Rotate bits to the left.

  • ror – Rotate bits to the right.

  • set – Set bit(s) to 1 or 0.

Additional special methods#

The special methods available for the Bits class are all available, plus some which will modify the bitstring:

  • [] – Set an element or slice.

  • del – Delete an element or slice.

  • += – Append bitstring to the current bitstring.

  • *= – Concatenate multiple copies of the current bitstring.

  • <<= – Shift bits in-place to the left.

  • >>= – Shift bits in-place to the right.

  • &= – In-place bit-wise AND between two bitstrings.

  • |= – In-place bit-wise OR between two bitstrings.

  • ^= – In-place bit-wise XOR between two bitstrings.

BitArray objects have the same properties as Bits, except that they are all (with the exception of len) writable as well as readable.

Reader#

Reader wraps a Bits or BitArray with a current bit position.

Reader(bits: Bits | BitArray, pos: int = 0)

Methods#

  • align – Move forward to the next multiple of a bit boundary.

  • bookmark – Context manager that restores pos afterwards.

  • from_file – Create a reader over the contents of a file.

  • peek_bits – Peek at a number of bits.

  • peek_value – Peek at and interpret next bits as a single item.

  • read_array – Read several items of one dtype as an Array.

  • read_bits – Read a number of bits.

  • read_list – Read and interpret next bits as a list of items.

  • read_past – Read up to and including the next occurrence of a bitstring.

  • read_to – Read up to but not including the next occurrence of a bitstring.

  • read_value – Read and interpret next bits as a single dtype.

  • seek_back_to – Search backwards, moving pos to the match.

  • seek_past – Search forwards, moving pos past the match.

  • seek_to – Search forwards, moving pos to the match.

Properties#

  • at_end – Whether the position is at the end of the data.

  • bits – The wrapped Bits or BitArray object.

  • bytepos – The current byte position.

  • pos – The current bit position.

  • remaining – The number of bits left to read.

Array#

A bitstring Array is a contiguously allocated sequence of bitstrings of the same type. It is similar to the array type in the array module, except that it is far more flexible.

Array(dtype: str | Dtype, initializer, trailing_bits)

The dtype can be any single fixed-length token as described in Format tokens and Compact format strings.

The initializer is an iterable of values appropriate to the dtype, such as a list, another bitstring.Array or an array.array. To create an Array from raw binary data use Array.from_bytes, and to create one full of zeroed items use Array.from_zeros.

The trailing_bits typically isn’t used in construction, and specifies bits left over after interpreting the stored binary data according to the data type dtype.

Both the dtype and the underlying bit data (stored as a BitArray) can be freely modified after creation, and element-wise operations can be used on the Array. Modifying the data or format after creation may cause the trailing_bits to not be empty.

Initialization examples:

Array('>H', [1, 10, 20])
Array.from_bytes('i4', stored_bytes)
Array.from_zeros('u8', 100)

Methods#

  • append – Append a single item to the end of the Array.

  • astype – Cast the Array to a new dtype.

  • byteswap – Change byte endianness of all items.

  • count – Count the number of occurrences of a value.

  • equals – Compare with another Array for exact equality.

  • extend – Append multiple items to the end of the Array from an iterable.

  • from_bytes – Create a new Array with binary data from a bytes-like object.

  • from_file – Create a new Array with items read from a file path or binary file object.

  • from_zeros – Create a new Array containing zeroed items.

  • insert – Insert an item at a given position.

  • pop – Return and remove an item.

  • pp – Pretty print the Array.

  • reverse – Reverse the order of all items.

  • to_bytes – Return Array data as bytes object, padding with zero bits at the end if needed.

  • to_file – Write Array data to a file, padding with zero bits at the end if needed.

  • to_list – Return Array items as a list.

Special methods#

These non-mutating special methods are available. Where appropriate they return a new Array.

  • [] – Get an element or slice.

  • bool() – False if empty; any other Array is ambiguous and raises.

  • + – Add value to each element.

  • - – Subtract value from each element.

  • * – Multiply each element by a value.

  • / – Divide each element by a value.

  • // – Floor divide each element by a value.

  • % – Take modulus of each element with a value.

  • << – Shift value of each element to the left.

  • >> – Shift value of each element to the right.

  • & – Bit-wise AND of each element.

  • | – Bit-wise OR of each element.

  • ^ – Bit-wise XOR of each element.

  • - – Unary minus of each element.

  • abs() – Absolute value of each element.

For example:

>>> b = Array('i6', [30, -10, 1, 0])
>>> b >> 2
Array('i6', [7, -3, 0, 0])
>>> b + 1
Array('i6', [31, -9, 2, 1])
>>> b + b
ValueError: Applying operator 'add' between Arrays caused 1 errors. First error at index 0 was: "Value 60 does not fit in 6 signed bits."

Results still have to fit the Array’s dtype, so the last line fails because 30 + 30 is outside the range of 'i6'.

Comparison operators will output an Array with a dtype of 'bool'.

  • == / != – Equality tests.

  • < – Less than comparison.

  • <= – Less than or equal comparison.

  • > – Greater than comparison.

  • >= – Greater than or equal comparison.

Mutating versions of many of the methods are also available.

  • [] – Set an element or slice.

  • del – Delete an element or slice.

  • += – Add value to each element in-place.

  • -= – Subtract value from each element in-place.

  • *= – Multiply each element by a value in-place.

  • /= – Divide each element by a value in-place.

  • //= – Floor divide each element by a value in-place.

  • %= – Take modulus of each element with a value in-place.

  • <<= – Shift bits of each element to the left in-place.

  • >>= – Shift bits of each element to the right in-place.

  • &= – In-place bit-wise AND of each element.

  • |= – In-place bit-wise OR of each element.

  • ^= – In-place bit-wise XOR of each element.

Example:

>>> a = Array('f16', [1.5, 2.5, 7, 1000])
>>> a[::2] *= 3.0  # Multiply every other f16 value in-place
>>> a
Array('f16', [4.5, 2.5, 21.0, 1000.0])

The bit-wise logical operations (&, |, ^) are performed on each element with a Bits object, which must have the same length as the Array elements. The other element-wise operations are performed on the interpreted data, not on the bit-data. For example this means that the shift operations won’t work on floating point formats.

Properties#

  • data – The complete binary data in a BitArray object. Can be modified in place, and can be set to another BitArray.

  • dtype – The data type or typecode. Can be freely modified.

  • itemsize – The length in bits of a single item. Read only.

  • trailing_bits – If the data length is not a multiple of itemsize, this BitArray gives the leftovers at the end of the data.

Dtype#

A data type (or ‘dtype’) concept is used in the bitstring module to encapsulate how to pack, unpack and present different bit interpretations.

Dtype(token: str | Dtype, /, length: int | None = None)

Creates a Dtype object. Dtypes are immutable and cannot be changed after creation.

The first parameter is a format token string that can optionally include a length.

If appropriate, the length parameter can be used to specify the length of the dtype.

Methods#

  • pack – Pack a value into a bitstring.

  • unpack – Unpack a bitstring to find its value.

Properties#

All properties are read-only.

  • bitlength – The number of bits needed to represent a single instance of the data type.

  • is_signed – If True then the data type represents a signed quantity.

  • length – The length of the data type, in bits except for bytes which counts bytes.

  • name – A string giving the name of the data type.

  • return_type – The type of the value returned by the unpack method.

  • variable_length – If True then the length of the data type varies, and shouldn’t be specified.

General Information#

Format tokens#

Format strings are used when constructing bitstrings, as well as reading, packing and unpacking them, as well as giving the format for Array objects. They can also be auto promoted to bitstring when appropriate - see The auto initialiser.

'i:n'

n bits as a signed integer.

'u:n'

n bits as an unsigned integer.

'ibe:n'

n bits as a byte-wise big-endian signed integer.

'ube:n'

n bits as a byte-wise big-endian unsigned integer.

'ile:n'

n bits as a byte-wise little-endian signed integer.

'ule:n'

n bits as a byte-wise little-endian unsigned integer.

'f:n'

n bits as a big-endian floating point number.

'float:n'

Alias for 'f:n'.

'fbe:n'

Alias for 'f:n'.

'fle:n'

n bits as a little-endian floating point number.

'hex:n'

n bits as a hexadecimal string.

'oct:n'

n bits as an octal string.

'bin:n'

n bits as a binary string.

'bits:n'

n bits as a new bitstring.

'bytes:n'

n bytes as a bytes object.

'bool[:1]'

Next bit as a boolean (True or False).

'pad:n'

Next n bits are ignored when reading, and set to zero when creating.

The ':' before the length is optional when the length is a number, so 'u8' and 'u:8' are the same token. It is mostly omitted in this documentation, except where it improves readability.

The colon is required when the length is a keyword rather than a number, as in pack('u:n=5', n=8), so that the dtype name can be told from the keyword.

Every token above is also a property on Bits, and a settable property on BitArray, except for 'pad' and 'bits'. Padding isn’t an interpretation of data, and a bits property would just return the bitstring itself, so both are usable only in a format string.

The longer int, uint and float names remain as compatibility aliases for i, u and f. Longer endian-specific names such as intle, uintbe and floatle also remain as compatibility aliases for ile, ube and fle. The fbe and floatbe names are aliases for f.

See also Exotic Floating Point Formats and Exponential-Golomb Codes for other types that can be used in format token strings.

Bitstring literals#

To make a literal quantity (one that directly represents a sequence of bits) you can use any of the format tokens above followed by an '=' and a value to initialise with. For example:

s = BitArray('f32=10.125, i7=-9')
s.append('hex=abc')

You can also create binary, octal and hexadecimal literals by starting a string with '0b', '0o' and '0x' respectively:

t = BitArray('0b101')
t += '0x001f'

Compact format strings#

Another option is to use a format specifier similar to those used in the struct and array modules. These consist of a character to give the endianness, followed by more single characters to give the format.

The endianness character must start the format string:

'>'

Big-endian

'<'

Little-endian

Note

For ‘network’ endianness use '>' as network and big-endian are equivalent.

This is followed by at least one of these format characters:

'b'

8 bit signed integer

'B'

8 bit unsigned integer

'h'

16 bit signed integer

'H'

16 bit unsigned integer

'i' / 'l'

32 bit signed integer

'I' / 'L'

32 bit unsigned integer

'q'

64 bit signed integer

'Q'

64 bit unsigned integer

'e'

16 bit floating point number

'f'

32 bit floating point number

'd'

64 bit floating point number

The exact type is determined by combining the endianness character with the format character, but rather than give an exhaustive list a single example should explain:

'>h'

Big-endian 16 bit signed integer

ibe16

'<h'

Little-endian 16 bit signed integer

ile16

As you can see both are signed integers in 16 bits, the only difference is the endianness. For the single byte codes 'b' and 'B' the endianness doesn’t make any difference, but you still need to specify one so that the format string can be parsed correctly.

'l' and 'L' are synonyms for 'i' and 'I', as they are in the struct module when standard sizes are used, which is always the case here.

A single compact code is accepted anywhere a dtype name is, including Dtype, Array, pack, unpack and the Reader read methods. Several codes can be combined in one string, as in '>hhl', wherever a format string with several tokens makes sense.

The code is converted to the equivalent dtype as soon as it is used, so it is the dtype name that you’ll see afterwards in reprs and error messages: Array('>L', [1, 2]) reprs as Array('ube32', [1, 2]).

Module level#

Functions#

  • pack – Create a new Bits object according to a format string and values.

Exceptions#

  • ReadError – Reading or peeking past the end of a bitstring. Subclasses ValueError.

Everything else is raised as a standard Python exception, usually ValueError or TypeError.