Clone wiki

BitReader / Home


BitReader is a small Python utility library for reading bits from bytes by specifying the structure of data with JSON compatible syntax to avoid the unreadable mess of bitwise operations. Little & big endian data supported.

Licensed under MIT.

Simple example

from bitreader import BitReader, bytes2str, str2bytes

# A specification defines names of variables and how many bits they need
spec    = ['test1', 12, 'test2', 4]

reader = BitReader(spec)
result =[0xfe, 0xda]) # Or just

# The result contains the variables as attributes
> '0xfed'

> '0xa'

# And you can convert the result back to binary format
> array('B', [254, 218])

This can be used to read static data, but very often the data is dynamic or we need to read a list of data elements. That can be done with subspecification.


# Dynamic data or arrays can be read with subspecification
# described with a dict.
spec   = [
    'length', 8,
    # 'sizeby' is used to set the field which tells the length
    # of the string we are reading. We could also hard code the size
    # with 'size' key instead of 'sizeby'. 'size' tells the length
    # of the data and data defined in 'spec' is read until the given
    # size is exceeded or matched. Hopefully matched. There's also
    # 'count' and 'countby' which can be used to read the data
    # exactly the given times. Here, we could use either one.
        'sizeby' : 'length',
        'spec'   : ['char',8]
reader = BitReader(spec)

# Create test data
text   = "Hello World!"
data   = [len(text)] + str2bytes(text)

# Read the data to BitData object
bitdata =
# The text is stored in as list of BitData objects
# Each BitData object has char attribute holding a single
# character. We need to join them together to form the string.
print bytes2str(, attribute="char")
> 'Hello World!'