About

This module is intended to have a similar interface as the python struct module, but working on bits instead of primitive data types (char, int, ...).

Project homepage: https://github.com/eerimoq/bitstruct

Documentation: http://bitstruct.readthedocs.org/en/latest

Installation

pipinstallbitstruct

Example usage

A basic example of packing and unpacking four integers using the format string 'u1u3u4s16':

>>>frombitstructimport*>>>pack('u1u3u4s16', 1, 2, 3, -4)
b'\xa3\xff\xfc'>>>unpack('u1u3u4s16', b'\xa3\xff\xfc')
(1, 2, 3, -4)
>>>calcsize('u1u3u4s16')
24

An example compiling the format string once, and use it to pack and unpack data:

>>>importbitstruct>>>cf=bitstruct.compile('u1u3u4s16')
>>>cf.pack(1, 2, 3, -4)
b'\xa3\xff\xfc'>>>cf.unpack(b'\xa3\xff\xfc')
(1, 2, 3, -4)

The unpacked values can be named by assigning them to variables or by wrapping the result in a named tuple:

>>>frombitstructimport*>>>fromcollectionsimportnamedtuple>>>MyName=namedtuple('myname', [ 'a', 'b', 'c', 'd' ])
>>>unpacked=unpack('u1u3u4s16', b'\xa3\xff\xfc')
>>>myname=MyName(*unpacked)
>>>mynamemyname(a=1, b=2, c=3, d=-4)
>>>myname.c3

An example of packing and unpacking an unsinged integer, a signed integer, a float, a boolean, a byte string and a string:

>>>frombitstructimport*>>>pack('u5s5f32b1r13t40', 1, -1, 3.75, True, b'\xff\xff', 'hello')
b'\x0f\xd0\x1c\x00\x00?\xffhello'>>>unpack('u5s5f32b1r13t40', b'\x0f\xd0\x1c\x00\x00?\xffhello')
(1, -1, 3.75, True, b'\xff\xf8', 'hello')
>>>calcsize('u5s5f32b1r13t40')
96

The same format string and values as in the previous example, but using LSB (Least Significant Bit) first instead of the default MSB (Most Significant Bit) first:

>>>frombitstructimport*>>>pack('<u5s5f32b1r13t40', 1, -1, 3.75, True, b'\xff\xff', 'hello')
b'\x87\xc0\x00\x03\x80\xbf\xff\xf666\xa6\x16'>>>unpack('<u5s5f32b1r13t40', b'\x87\xc0\x00\x03\x80\xbf\xff\xf666\xa6\x16')
(1, -1, 3.75, True, b'\xff\xf8', 'hello')
>>>calcsize('<u5s5f32b1r13t40')
96

An example of unpacking values from a hexstring and a binary file:

>>>frombitstructimport*>>>frombinasciiimportunhexlify>>>unpack('s17s13r24', unhexlify('0123456789abcdef'))
(582, -3751, b'\xe2j\xf3')
>>>withopen("test.bin", "rb") asfin:
... unpack('s17s13r24', fin.read(8))
...
...
(582, -3751, b'\xe2j\xf3')

Change endianness of the data with byteswap, and then unpack the values:

>>>frombitstructimport*>>>packed=pack('u1u3u4s16', 1, 2, 3, 1)
>>>unpack('u1u3u4s16', byteswap('12', packed))
(1, 2, 3, 256)

Contributing

1. Fork the repository.

2. Install prerequisites.

   pip install -r requirements.txt
   

3. Implement the new feature or bug fix.

4. Implement test case(s) to ensure that future changes do not break legacy.

5. Run the tests.

   make test
   

6. Create a pull request.