Quick Reference

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

There are four classes that are bit containers, so that each element is a single bit. They differ based on whether they can be modified after creation and on whether they have the concept of a current bit position.

Class

Mutable?

Streaming methods?

Bits

        ✘

        ✘

An efficient, immutable container of bits.

BitArray

        ✔

        ✘

Like Bits but it can be changed after creation.

ConstBitStream

        ✘

        ✔

Immutable like Bits but with a bit position and reading methods.

BitStream

        ✔

        ✔

Mutable like BitArray but with a bit position and reading methods.

The final class is a flexible container whose elements are fixed-length bitstrings.

Array

        ✔

        ✘

An efficient list-like container where each item has a fixed-length binary format.


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: Optional[int], offset: Optional[int], **kwargs)

The first parameter (usually referred to as auto) can be many different types, including parsable strings, a file handle, a bytes or bytearray object, an integer or an iterable.

A single initialiser from kwargs can be used instead of auto, including bin, hex, oct, bool, uint, int, float, bytes and filename.

Examples:

Bits('0xef')
Bits(float=-50.5, length=32)
Bits('uint10=99')
Bits(uint=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.

  • 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.

  • tobitarray – Return bitstring as a bitarray object from the bitarray package.

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

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

  • 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.

  • + – 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 / b – The bitstring as a binary string.

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

  • bytes – The bitstring as a bytes object.

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

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

  • floatne – Interpret as a native-endian floating point number.

  • e4m3float – Interpret as an 8 bit float with 1:4:3 format.

  • e5m2float – Interpret as an 8 bit float with 1:5:2 format.

  • bfloat / bfloatbe – Interpret as a big-endian bfloat floating point number.

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

  • bfloatne – Interpret as a native-endian bfloat floating point number.

  • hex / h – The bitstring as a hexadecimal string.

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

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

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

  • intne – Interpret as a native-endian signed integer.

  • len – Length of the bitstring in bits.

  • oct / o – The bitstring as an octal string.

  • se – Interpret as a signed exponential-Golomb code.

  • ue – Interpret as an unsigned exponential-Golomb code.

  • sie – Interpret as a signed interleaved exponential-Golomb code.

  • uie – Interpret as an unsigned interleaved exponential-Golomb code.

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

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

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

  • uintne – Interpret as a native-endian unsigned integer.


BitArray

BitsBitArray

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.


ConstBitStream

BitsConstBitStream

ConstBitStream adds a bit position and methods to read and navigate in an immutable bitstream. If you wish to use streaming methods on a large file without changing it then this is often the best class to use.

The constructor is the same as for Bits / BitArray but with an optional current bit position.

ConstBitStream(auto, length: Optional[int], offset: Optional[int], pos: int = 0, **kwargs)

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

Additional methods

  • bytealign – Align to next byte boundary.

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

  • peeklist – Peek at and interpret next bits as a list of items.

  • read – Read and interpret next bits as a single item.

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

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

Additional properties

  • bytepos – The current byte position in the bitstring.

  • pos – The current bit position in the bitstring.


BitStream

BitsBitArray / ConstBitStreamBitStream

BitStream contains all of the ‘stream’ elements of ConstBitStream and adds all of the mutating methods of BitArray. The constructor is the same as for ConstBitStream. It has all the methods, special methods and properties of the Bits, BitArray and ConstBitArray classes.

It is the most general of the four classes, but it is usually best to choose the simplest class for your use case.


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, initializer, trailing_bits)

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

The inititalizer will typically be an iterable such as a list, but can also be many other things including an open binary file, a bytes or bytearray object, another bitstring.Array or an array.array.

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('float16', a_file_object)
Array('int4', stored_bytes)

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 occurences of a value.

  • equals – Compare with another Array for exact equality.

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

  • fromfile – Append items read from a file object.

  • 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.

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

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

  • tolist – 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.

  • + – 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
Array('i6', [30, -10, 1, 0, 30, -10, 1, 0])

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('float16', [1.5, 2.5, 7, 1000])
>>> a[::2] *= 3.0  # Multiply every other float16 value in-place
>>> a
Array('float16', [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 freely modified.

  • 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 the dtype length, this BitArray gives the leftovers at the end of the data.


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.

The ':' before the length is optional, and is mostly omitted in the documentation, except where it improves readability.

The hex, bin, oct, int, uint and float properties can all be shortened to just their initial letter.

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('float32=10.125, int7=-9')
s.append('hex:abc')

You can also create binary, octal and hexadecimal literals by starting a string with '0b', '0o' and '0ox' 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

'='

Native-endian

Note

  • For native-endian '@' and '=' can both be used and are equivalent. The '@' character was required for native-endianness prior to version 4.1 of bitstring.

  • 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

'l'

32 bit signed integer

'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

intbe16

'<h'

Little-endian 16 bit signed integer

intle16

'=h'

Native-endian 16 bit signed integer

intne16

As you can see all three are signed integers in 16 bits, the only difference is the endianness. The native-endian '=h' will equal the big-endian '>h' on big-endian systems, and equal the little-endian '<h' on little-endian systems. 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.


Module level

Functions

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

Exceptions

  • Error – Base class for module exceptions.

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

  • InterpretError – Inappropriate interpretation of binary data.

  • ByteAlignError – Whole-byte position or length needed.

  • CreationError – Inappropriate argument during bitstring creation.

Module variables

  • bytealigned – Determines whether a number of methods default to working only on byte boundaries.

  • lsb0 – If True, index bits with the least significant bit (the final bit) as bit zero.