binspec 1.0.0

BinSpec (short for Binary Specification) is a binary parsing library built with Python 3.

BinSpec

BinSpec (short for Binary Specification) is a binary parsing library built with Python 3.

Installation

Install BinSpec from PyPi:

pip install binspec

Usage

BinSpec is based around the Specification class which is used in tandem with SpecTypes to parse and validate binary data.

from binspec import Specification
from binspec.types import String, Int, Array

data = bytearray()
data.append("MAGIC".encode("utf8"))
data.append(0b01110110)
data.append(0b11001100)

spec = Specification(data)
magic = spec.expect(String(length=5, encoding="utf8"))

if magic != "MAGIC":
    spec.fail("Expected magic string: MAGIC") # Manually fail and raise a SpecError.

n = spec.expect(Int(bytes=1))

print(n)
# 0b01110110 -> 118

flags = spec.expect(Array(Int(bits=2), length=4))

print(flags)
# [ 0b11, 0b00, 0b11, 0b00 ] -> [ 3, 0, 3, 0 ]

Currently, the builtin SpecTypes consist of String, Int, Int8, Int16, Int32, Int64, Packed, Array Bytes, and Bits. Refer to their docstrings for more inforomation.

In practice, data should come from an outside source, such as FileIO.read(). In the best case, a conversion to BytesIO is not necessary and stream-like object can be used directly to supply Specification.

from binspec import Specification
from binspec.types import String, Int, Array

with open("my_imaginary_file.binary", "rb") as f:
    spec = Specification(f)

    # ...

UI

Additonally, a simple webpage is provided to visualize a specification via a webpage.

from binspec.ui import show

data = bytearray()
# ...

spec = Specification(data)
show(spec, data) # A bytes-like copy of the data must be provided to show.

Creating Custom SpecTypes

To create a custom SpecType, create a class which derives from SpecType:

from binspec.types import SpecType

class ByteAsAString(SpecType):
    pass

For this example, the custom SpecType will parse a byte as a string of 1s and 0s.

Continuing, SpecType requires two abstract methods, get_bit_length and parse to be implemented.

from binspec.types import SpecType

class BytesAsAString(SpecType):
    def __init__(self, *, byte_count: int):
        self.byte_count = byte_count

    def get_bit_length(self):
        return self.byte_count * 8

    def parse(self, bits: bytes) -> str:
        s = ""

        for b in bits:
            if b == 0:
                s += "0"
            else:
                s += "1"

        return s

And voila, now use ByteAsAString in Specification.expect (or another SpecType, like Array) to parse it.

from binspec import Specification
from binspec.types import Array

data = bytearray()
data.append(0b11110000)
data.append(0b10101010)

data.append(0b10101010)
data.append(0b11110000)

spec = Specification(data)

s = spec.expect(BytesAsAString(byte_count=2))

print(s)
# "1111000010101010"

arr = spec.expect(Array(BytesAsAString(byte_count=1), length=2))

print(arr)
# [ "10101010", "11110000" ]