Functions¶
pack¶
- pack(format[, *values, **kwargs])¶
Packs the values and keyword arguments according to the format string and returns a new
BitStream.
The format string consists of comma separated tokens, see Format tokens and Compact format strings for details.
The tokens can be ‘literals’, like 0xef, 0b110, uint8=55, etc. which just represent a set sequence of bits.
They can also have the value missing, in which case the values contained in *values will be used.
>>> a = pack('bin3, hex4', '001', 'f')
>>> b = pack('uint10', 33)
A dictionary or keyword arguments can also be provided. These will replace items in the format string.
>>> c = pack('int:a=b', a=10, b=20)
>>> d = pack('int8=a, bin=b, int4=a', a=7, b='0b110')
Plain names can also be used as follows:
>>> e = pack('a, b, b, a', a='0b11', b='0o2')
Tokens starting with an endianness identifier (<, > or =) implies a struct-like compact format string (see Compact format strings). For example this packs three little-endian 16-bit integers:
>>> f = pack('<3h', 12, 3, 108)
And of course you can combine the different methods in a single pack.
A ValueError will be raised if the *values are not all used up by the format string, and if a value provided doesn’t match the length specified by a token.
As an example of using just the *values arguments we can say:
s = bitstring.pack('hex32, uint12, uint12', '0x000001b3', 352, 288)
which is equivalent to initialising as:
s = BitStream('0x0000001b3, uint12=352, uint12=288')
The advantage of the pack function is if you want to write more general code for creation.
def foo(a, b, c, d):
return bitstring.pack('uint8, 0b110, int6, bin, bits', a, b, c, d)
s1 = foo(12, 5, '0b00000', '')
s2 = foo(101, 3, '0b11011', s1)
Note how you can use some tokens without sizes (such as bin and bits in the above example), and use values of any length to fill them.
If the size had been specified then a ValueError would be raised if the parameter given was the wrong length.
Note also how bitstring literals can be used (the 0b110 in the bitstring returned by foo) and these don’t consume any of the items in *values.
You can also include keyword, value pairs (or an equivalent dictionary) as the final parameter(s). The values are then packed according to the positions of the keywords in the format string. This is most easily explained with some examples. Firstly the format string needs to contain parameter names:
format = 'hex32=start_code, uint12=width, uint12=height'
Then we can make a dictionary with these parameters as keys and pass it to pack:
d = {'start_code': '0x000001b3', 'width': 352, 'height': 288}
s = bitstring.pack(format, **d)
Another method is to pass the same information as keywords at the end of pack’s parameter list:
s = bitstring.pack(format, width=352, height=288, start_code='0x000001b3')
You can include constant bitstring tokens such as ‘0x101’, ‘0xff’, ‘uint7=81’ etc. and also use a keyword for the length specifier in the token, for example:
s = bitstring.pack('0xabc, int:n=-1', n=100)
Finally it is also possible just to use a keyword as a token:
s = bitstring.pack('hello, world', world='0x123', hello='0b110')
Options¶
The bitstring module has an options object that allows certain module-wide behaviours to be set.
lsb0¶
- bitstring.options.lsb0 : bool
By default bit numbering in the bitstring module is done from ‘left’ to ‘right’. That is, from bit 0 at the start of the data to bit n - 1 at the end. This allows bitstrings to be treated like an ordinary Python container that is only allowed to contain single bits.
The lsb0 option allows bitstrings to use Least Significant Bit Zero
(LSB0) bit numbering; that is the right-most bit in the bitstring will
be bit 0, and the left-most bit will be bit (n-1), rather than the
other way around. LSB0 is a more natural numbering
system in many fields, but is the opposite to Most Significant Bit
Zero (MSB0) numbering which is the natural option when thinking of
bitstrings as standard Python containers.
For example, if you set a bitstring to be the binary 010001111 it will be stored in the same way for MSB0 and LSB0 but slicing, reading, unpacking etc. will all behave differently.
bit index |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
|---|---|---|---|---|---|---|---|---|---|
value |
|
|
|
|
|
|
|
|
|
In MSB0 everything behaves like an ordinary Python container. Bit zero is the left-most bit and reads/slices happen from left to right.
bit index |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
|---|---|---|---|---|---|---|---|---|---|
value |
|
|
|
|
|
|
|
|
|
In LSB0 the final, right-most bit is labelled as bit zero. Reads and slices happen from right to left.
When bitstrings (or slices of bitstrings) are interpreted as integers and other types the left-most bit is considered as the most significant bit. It’s important to note that this is the case irrespective of whether the first or last bit is considered the bit zero, so for example if you were to interpret a whole bitstring as an integer, its value would be the same with and without lsb0 being set to True.
To illustrate this, for the example above this means that the bin and int representations would be 010001111 and 143 respectively for both MSB0 and LSB0 bit numbering.
To switch from the default MSB0, use bitstring.options.lsb0. This defaults to False and unless explicitly stated all examples and documentation related to the bitstring module use the default MSB0 indexing.
>>> bitstring.options.lsb0 = True
Slicing is still done with the start bit smaller than the end bit. For example:
>>> s = Bits('0b010001111')
>>> s[0:5] # LSB0 so this is the right-most five bits
Bits('0b01111')
>>> s[0]
True
Note
In some standards and documents using LSB0 notation the slice of the final five bits would be shown as s[5:0], which is reasonable as bit 5 comes before bit 0 when reading left to right, but this notation isn’t used in this module as it clashes too much with the usual Python notation.
Negative indices work as you’d expect, with the first stored
bit being s[-1] and the final stored bit being s[-n].
Reading, peeking and unpacking of bitstrings are also affected by the lsb0 flag, so reading always increments the bit position, and will move from right to left if lsb0 is True. Because of the way that exponential-Golomb codes are read (with the left-most bits determining the length of the code) these interpretations are not available in LSB0 mode, and using them will raise an exception.
For BitStream and ConstBitStream objects changing the value of bitstring.options.lsb0 invalidates the current position in the bitstring, unless that value is 0, and future results are undefined. Basically don’t perform reads or change the current bit position before switching the bit numbering system!
bytealigned¶
- bitstring.options.bytealigned : bool
A number of methods take a bytealigned parameter to indicate that they should only work on byte boundaries (e.g. find, findall, split and replace). This parameter defaults to bitstring.options.bytealigned, which itself defaults to False, but can be changed to modify the default behaviour of the methods. For example:
>>> a = BitArray('0x00 ff 0f ff')
>>> a.find('0x0f')
(4,) # found first not on a byte boundary
>>> a.find('0x0f', bytealigned=True)
(16,) # forced looking only on byte boundaries
>>> bitstring.options.bytealigned = True # Change default behaviour
>>> a.find('0x0f')
(16,)
>>> a.find('0x0f', bytealigned=False)
(4,)
If you’re only working with bytes then this can help avoid some errors and save some typing.
mxfp_overflow¶
- bitstring.options.mxfp_overflow : str
This option can be used to change the out-of-range behaviour of some 8-bit floating point types.
The default value is 'saturate' but it can also be set to 'overflow'.
See Exotic Floating Point Formats for details.
no_color¶
- bitstring.options.no_color : bool
The bitstring module can use ANSI escape codes to colourise the output of the Bits.pp and Array.pp methods.
If a NO_COLOR environment variable is found and is not an empty string then this option will be set to True, otherwise it defaults to False.
See https://no-color.org for more information.
The terminal colours can also be turned off by setting bitstring.options.no_color to True.
Command Line Usage¶
The bitstring module can be called from the command line to perform simple operations. For example:
$ python -m bitstring int16=-400
0xfe70
$ python -m bitstring float32=0.2 bin
00111110010011001100110011001101
$ python -m bitstring 0xff "3*0b01,0b11" uint
65367
$ python -m bitstring hex=01, uint12=352.hex
01160
Command-line parameters are concatenated and a bitstring created from them. If the final parameter is either an interpretation string or ends with a . followed by an interpretation string then that interpretation of the bitstring will be used when printing it. If no interpretation is given then the bitstring is just printed.
Exceptions¶
- exception Error(Exception)¶
Base class for all module exceptions.
- exception InterpretError(Error, ValueError)¶
Inappropriate interpretation of binary data. For example using the ‘bytes’ property on a bitstring that isn’t a whole number of bytes long.
- exception ByteAlignError(Error)¶
Whole-byte position or length needed.
- exception CreationError(Error, ValueError)¶
Inappropriate argument during bitstring creation.
- exception ReadError(Error, IndexError)¶
Reading or peeking past the end of a bitstring.