bitstruct - Interpret strings as packed binary data¶
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, …).
Documentation: http://bitstruct.readthedocs.org/en/latest
Installation¶
pip install bitstruct
Example usage¶
See the test suite: https://github.com/eerimoq/bitstruct/blob/master/tests/test_bitstruct.py
A basic example of packing/unpacking four integers:
>>> 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
The unpacked fields 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
An example of packing/unpacking a unsinged 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', u'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', u'hello')
>>> calcsize('u5s5f32b1r13t24')
80
The same format 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('<u5s5f32b1r13', 1, -1, 3.75, True, b'\xff\xff')
b'\x87\xc0\x00\x03\x80\xbf\xff'
>>> unpack('<u5s5f32b1r13', b'\x87\xc0\x00\x03\x80\xbf\xff')
(1, -1, 3.75, True, b'\xff\xf8')
>>> calcsize('<u5s5f32b1r13')
56
An example of unpacking values from a hexstring and a binary file:
>>> from bitstruct import *
>>> unpack('s17s13r24', '0123456789abcdef'.decode('hex'))
(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)
Functions¶
-
bitstruct.
pack
(fmt, *args)[source]¶ Return a byte string containing the values v1, v2, … packed according to the given format. If the total number of bits are not a multiple of 8, padding will be added at the end of the last byte.
Parameters: - fmt – Bitstruct format string. See format description below.
- args – Variable argument list of values to pack.
Returns: A byte string of the packed values.
fmt is a string of bitorder-type-length groups, and optionally a byteorder identifier afer the groups. Bitorder and byteorder may be omitted.
Bitorder is either “>” or “<”, where “>” means MSB first and “<” means LSB first. If bitorder is omitted, the previous values’ bitorder is used for the current value. For example, in the format string “u1<u2u3” u1 is MSB first and both u2 and u3 are LSB first.
Byteorder is either “>” or “<”, where “>” means most significant byte first and “<” means least significant byte first. If byteorder is omitted, most significant byte first is used.
There are seven types; ‘u’, ‘s’, ‘f’, ‘b’, ‘t’, ‘r’ and ‘p’.
- ‘u’ – unsigned integer
- ‘s’ – signed integer
- ‘f’ – floating point number of 32 or 64 bits
- ‘b’ – boolean
- ‘t’ – text (ascii or utf-8)
- ‘r’ – raw, bytes
- ‘p’ – padding, ignore
Length is the number of bits to pack the value into.
Example format string with default bit and byte ordering: ‘u1u3p7s16’
Same format string, but with least significant byte first: ‘u1u3p7s16<’
Same format string, but with LSB first (‘<’ prefix) and least significant byte first (‘<’ suffix): ‘<u1u3p7s16<’
-
bitstruct.
unpack
(fmt, data)[source]¶ Unpack data (byte string, bytearray or list of integers) according to the given format. The result is a tuple even if it contains exactly one item.
Parameters: - fmt – Bitstruct format string. See pack() for details.
- data – Byte string of values to unpack.
Returns: A tuple of the unpacked values.
-
bitstruct.
calcsize
(fmt)[source]¶ Calculate the number of bits in given format.
Parameters: fmt – Bitstruct format string. Returns: Number of bits in format string.
-
bitstruct.
byteswap
(fmt, data, offset=0)[source]¶ Swap bytes in data according to fmt, starting at byte offset. fmt must be an iterable, iterating over number of bytes to swap. For example, the format string “24” applied to the byte string b’”3DU’ will produce the result b’UD3”’.
Parameters: - fmt – Swap format string.
- data – Byte string of data to swap.
- offset – Start offset into data.
Returns: Byte string of swapped bytes.