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 / 2.5 and for Python 2.6 / 3.x.

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

View the Documentation Here

It contains a walk-through of all the features and a complete reference section.

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 + 'int:20=40'
BitString('0x1af1af1af00028')

Reading data sequentially.

>>> b = BitString('0x160120f')
>>> b.read('hex:12')
'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

January 19th 2010: Version 1.2.0 for Python 2.6 and 3.x released

New 'Bits' class

Introducing a brand new class, Bits, representing an immutable sequence of bits.

The Bits class is the base class for the mutable BitString. The differences between Bits and BitStrings are:

1) Bits are immutable, so once they have been created their value cannot change. This of course means that mutating methods (append, replace, del etc.) are not available for Bits.

2) Bits are hashable, so they can be used in sets and as keys in dictionaries.

3) Bits are potentially more efficient than BitString, both in terms of computation and memory. The current implementation is only marginally more efficient though - this should improve in future versions.

You can switch from Bits to a BitString or vice versa by constructing a new object from the old.

>>> s = Bits('0xabcd')
>>> t = BitString(s)
>>> t.append('0xe')
>>> u = Bits(t)

The relationship between Bits and BitString is supposed to loosely mirror that between bytes and bytearray in Python 3.

Deprecation messages turned on

A number of methods have been flagged for removal in version 2. Deprecation warnings will now be given, which include an alternative way to do the same thing. All of the deprecated methods have simpler equivalent alternatives.

>>> t = s.slice(0, 2)
__main__:1: DeprecationWarning: Call to deprecated function slice.
Instead of 's.slice(a, b, c)' use 's[a:b:c]'.

The deprecated methods are: advancebit, advancebits, advancebyte, advancebytes, retreatbit, retreatbits, retreatbyte, retreatbytes, tell, seek, slice, delete, tellbyte, seekbyte, truncatestart and truncateend.

Initialise from bool

Booleans have been added to the list of types that can 'auto' initialise a bitstring.

>>> zerobit = BitString(False)
>>> onebit = BitString(True)

Improved efficiency

More methods have been speeded up, in particular some deletions and insertions.

Bug fixes

• A rare problem with truncating the start of bitstrings was fixed.

• A possible problem outputting the final byte in tofile() was fixed.