bitstring is a pure Python module designed to help make the creation, manipulation and analysis of binary data as simple and natural as possible.

BitStrings can be constructed from integers (big and little endian), hex, octal, binary, strings or files. They can be sliced, joined, reversed, inserted into, overwritten, etc. with simple functions or slice notation. They can also be read from, searched and replaced, and navigated in, similar to a file or stream.

Internally the data is efficiently stored as byte arrays, the module has been optimized for speed, and excellent code coverage is given by over 300 unit tests. It is available for Python 2.4+ and for Python 3.

To get updates on new releases you can subscribe to the project on freshmeat.

Documentation

The manual for the bitstring module is available as a PDF. It contains a walk-through of all the features and a complete reference section.

You can also view this on the Wiki.

Examples

Creation:

>>> a = BitString(bin='00101')
>>> b = BitString(a_file_object)
>>> c = BitString('0xff, 0b101, 0o65, uint:6=22')
>>> d = pack('intle:16, hex=a, 0b1', 100, a='0x34f')
>>> e = pack('<16h', *range(16))

Different interpretations, slicing and concatenation:

>>> a = BitString('0x1af')
>>> a.hex, a.bin, a.uint
('0x1af', '0b000110101111', 431)
>>> a[10:3:-1].bin
'0b1110101'
>>> 3*a + '0b100'
BitString('0o0657056705674')

Reading data sequentially.

>>> b = BitString('0x160120f')
>>> b.readbits(12).hex
'0x160'
>>> b.pos = 0
>>> b.read('uint:12')
352
>>> b.readlist('uint:12, bin:3')
[288, '0b111']

Searching, inserting and deleting:

>>> c = BitString('0b00010010010010001111')   # c.hex == '0x1248f'
>>> c.find('0x48')
True
>>> c.replace('0b001', '0xabc')
>>> c.insert('0b0000')
>>> c.delete(4, 12)

See the Wiki and the user manual for more examples.

News

October 10th 2009: Version 1.0 for Python 2.x and 3.x released

Version 1 is here!

This is the first release not to carry the 'beta' tag. It contains a couple of minor new features but is principally a release to fix the API. If you've been using an older version then you almost certainly will have to recode a bit. If you're not ready to do that then you may wish to delay updating.

So the bad news is that there are lots of small changes to the API. The good news is that all the changes are pretty trivial, the new API is cleaner and more 'Pythonic', and that by making it version 1.0 I'm promising not to tweak it again for some time.

For full details on the API changes and for earlier changes, see the release notes.

There is one version for Python 2.4 / 2.5 / 2.6 (version 1.0.0) and another for Python 3.0 / 3.1 (version 1.0.1).