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

pip install bitstruct

Example usage

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

>>> from bitstruct import *
>>> 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:

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

Use the pack into and unpack from functions to pack/unpack values at a bit offset into the data, in this example the bit offset is 5:

>>> from bitstruct import *
>>> data = bytearray(b'\x00\x00\x00\x00')
>>> pack_into('u1u3u4s16', data, 5, 1, 2, 3, -4)
>>> data
bytearray(b'\x05\x1f\xff\xe0')
>>> unpack_from('u1u3u4s16', data, 5)
(1, 2, 3, -4)

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

>>> from bitstruct import *
>>> from collections import namedtuple
>>> MyName = namedtuple('myname', ['a', 'b', 'c', 'd'])
>>> unpacked = unpack('u1u3u4s16', b'\xa3\xff\xfc')
>>> myname = MyName(*unpacked)
>>> myname
myname(a=1, b=2, c=3, d=-4)
>>> myname.c
3

Use the pack_dict and unpack_dict functions to pack/unpack values in dictionaries:

>>> from bitstruct import *
>>> names = ['a', 'b', 'c', 'd']
>>> pack_dict('u1u3u4s16', names, {'a': 1, 'b': 2, 'c': 3, 'd': -4})
b'\xa3\xff\xfc'
>>> unpack_dict('u1u3u4s16', names, b'\xa3\xff\xfc')
{'a': 1, 'b': 2, 'c': 3, 'd': -4}

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

>>> from bitstruct import *
>>> 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:

>>> from bitstruct import *
>>> 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:

>>> from bitstruct import *
>>> from binascii import unhexlify
>>> unpack('s17s13r24', unhexlify('0123456789abcdef'))
(582, -3751, b'\xe2j\xf3')
>>> with open("test.bin", "rb") as fin:
...     unpack('s17s13r24', fin.read(8))
...
...
(582, -3751, b'\xe2j\xf3')

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

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

Contributing

Fork the repository.
Install prerequisites.
```
pip install -r requirements.txt
```
Implement the new feature or bug fix.
Implement test case(s) to ensure that future changes do not break legacy.
Run the tests.
```
make test
```
Create a pull request.

Metadata

Release files for bitstruct 5.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bitstruct 5.2.1
File	Size	Uploaded
bitstruct-5.2.1.tar.gz	20.2 kB	Nov 21, 2018	Details

Built distribution (wheel)

Table of built distributions (wheels) for bitstruct 5.2.1
File	Interpreter	ABI	Platform	Reset
bitstruct-5.2.1-py2.py3-none-any.whl 9.4 kB Nov 21, 2018	Python 2, Python 3	none	any	Details

Total release size: 29.5 kB

Release files / bitstruct-5.2.1.tar.gz

Download URL	bitstruct-5.2.1.tar.gz
Size	20.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`0b489b3431b35161b1fea96b1234bf8f5f4709d9a431438c9dd440bafd0cb95d`
BLAKE2b-256 checksum How to use checksums	`83e5b982879be802c4e159b3932bf3664b559a493f34efd35fd3145c8eb90e46`
Upload date	Nov 21, 2018
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.8.1 pkginfo/1.3.2 requests/2.18.3 setuptools/38.5.0 requests-toolbelt/0.7.0 clint/0.5.1 CPython/2.7.14 Linux/4.13.0-46-generic`

Release files / bitstruct-5.2.1-py2.py3-none-any.whl

Download URL	bitstruct-5.2.1-py2.py3-none-any.whl
Size	9.4 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`d9ecfe8cf981c02d2d47d5465342f1a89260e40b8c92078c59bbf44873f61076`
BLAKE2b-256 checksum How to use checksums	`4c8af0c5c4cf184462cbe7bedeec837177e84ae6127c0207f9b00bf489a72d19`
Upload date	Nov 21, 2018
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.8.1 pkginfo/1.3.2 requests/2.18.3 setuptools/38.5.0 requests-toolbelt/0.7.0 clint/0.5.1 CPython/2.7.14 Linux/4.13.0-46-generic`