Package: bitstruct
AboutThis 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/bitstructDocumentation:https://bitstruct.readthedocs.ioInstallationpipinstallbitstructPerformanceParts of this package has been re-implemented in C for faster pack and
unpack operations. There are two independent C implementations;bitstruct.c, which is part of this package, and the standalone
packagecbitstruct. These implementations are only available in
CPython 3, and must be explicitly imported. By default the pure Python
implementation is used.To usebitstruct.c, doimport bitstruct.c as bitstruct.To usecbitstruct, doimport cbitstruct as bitstruct.bitstruct.chas a few limitations compared to the pure Python
implementation:Integers and booleans must be 64 bits or less.Text and raw must be a multiple of 8 bits.Bit endianness and byte order are not yet supported.byteswap()can only swap 1, 2, 4 and 8 bytes.Seecbitstructfor its limitations.MicroPythonThe C implementation has been ported toMicroPython. Seebitstruct-micropythonfor more details.Example usageA basic example ofpackingandunpackingfour 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')24An examplecompilingthe format string once, and use it topackandunpackdata:>>>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)Use thepack intoandunpack fromfunctions to pack/unpack
values at a bit offset into the data, in this example the bit offset
is 5:>>>frombitstructimport*>>>data=bytearray(b'\x00\x00\x00\x00')>>>pack_into('u1u3u4s16',data,5,1,2,3,-4)>>>databytearray(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:>>>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.c3Use thepack_dictandunpack_dictfunctions to pack/unpack
values in dictionaries:>>>frombitstructimport*>>>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 ofpackingandunpackingan unsigned 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')96The 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')96An example ofunpackingvalues 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 withbyteswap, and then unpack the
values:>>>frombitstructimport*>>>packed=pack('u1u3u4s16',1,2,3,1)>>>unpack('u1u3u4s16',byteswap('12',packed))(1,2,3,256)A basic example ofpackingandunpackingfour integers using the
format string'u1u3u4s16'using the C implementation:>>>frombitstruct.cimport*>>>pack('u1u3u4s16',1,2,3,-4)b'\xa3\xff\xfc'>>>unpack('u1u3u4s16',b'\xa3\xff\xfc')(1,2,3,-4)ContributingFork the repository.Install prerequisites.pip install -r requirements.txtImplement the new feature or bug fix.Implement test case(s) to ensure that future changes do not break
legacy.Run the tests.make testCreate a pull request.