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, …).
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)
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
An example of packing and unpacking an 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', '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)
Functions¶
-
bitstruct.
pack
(fmt, *args)[source]¶ Return a byte string containing the values v1, v2, … packed according to given format string fmt. 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 after 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 bothu2
andu3
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
andp
.u
– unsigned integers
– signed integerf
– floating point number of 16, 32, or 64 bitsb
– booleant
– text (ascii or utf-8)r
– raw, bytesp
– 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 given format string fmt. 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.
- fmt – Bitstruct format string. See
-
bitstruct.
calcsize
(fmt)[source]¶ Calculate the number of bits in given format string fmt.
Parameters: fmt – Bitstruct format string. See pack()
for details.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 stringb'\x00\x11\x22\x33\x44\x55'
will produce the resultb'\x11\x00\x55\x44\x33\x22'
.Parameters: - fmt – Swap format string.
- data – Byte string of data to swap.
- offset – Start offset into data.
Returns: Byte string of swapped bytes.
-
bitstruct.
compile
(fmt)[source]¶ Compile given format string fmt and return a
CompiledFormat
object that can be used to pack and/or unpack data multiple times.Parameters: fmt – Bitstruct format string. See pack()
for details.
Classes¶
-
class
bitstruct.
CompiledFormat
(fmt)[source]¶ A compiled format string that can be used to pack and/or unpack data multiple times.
Instances of this class are created by the factory function
compile()
.Parameters: fmt – Bitstruct format string. See pack()
for details.-
calcsize
()[source]¶ Calculate the number of bits in the compiled format string.
Returns: Number of bits in the format string.
-
pack
(*args)[source]¶ Return a byte string containing the values v1, v2, … packed according to the compiled format string. If the total number of bits are not a multiple of 8, padding will be added at the end of the last byte.
Parameters: args – Variable argument list of values to pack. Returns: A byte string of the packed values.
-