PyCon US is happening May 14th-22nd in Pittsburgh, PA USA.  Learn more

A powerful declarative symmetric parser/builder for binary data

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for arekbulski from gravatar.com arekbulski Avatar for gangesmaster from gravatar.com gangesmaster Avatar for MostAwesomeDude from gravatar.com MostAwesomeDude

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Arkadiusz Bulski, Tomer Filiba, Corbin Simpson
  • Tags construct, kaitai, declarative, data structure, struct, binary, symmetric, parser, builder, parsing, building, pack, unpack, packer, unpacker
  • Requires: Python >=3.6
Classifiers

Project description

Construct is a powerful declarative and symmetrical parser and builder for binary data.

Instead of writing imperative code to parse a piece of data, you declaratively define a data structure that describes your data. As this data structure is not code, you can use it in one direction to parse data into Pythonic objects, and in the other direction, to build objects into binary data.

The library provides both simple, atomic constructs (such as integers of various sizes), as well as composite ones which allow you form hierarchical and sequential structures of increasing complexity. Construct features bit and byte granularity, easy debugging and testing, an easy-to-extend subclass system, and lots of primitive constructs to make your work easier:

  • Fields: raw bytes or numerical types

  • Structs and Sequences: combine simpler constructs into more complex ones

  • Bitwise: splitting bytes into bit-grained fields

  • Adapters: change how data is represented

  • Arrays/Ranges: duplicate constructs

  • Meta-constructs: use the context (history) to compute the size of data

  • If/Switch: branch the computational path based on the context

  • On-demand (lazy) parsing: read and parse only what you require

  • Pointers: jump from here to there in the data stream

  • Tunneling: prefix data with a byte count or compress it

Example

A Struct is a collection of ordered, named fields:

>>> format = Struct(
...     "signature" / Const(b"BMP"),
...     "width" / Int8ub,
...     "height" / Int8ub,
...     "pixels" / Array(this.width * this.height, Byte),
... )
>>> format.build(dict(width=3,height=2,pixels=[7,8,9,11,12,13]))
b'BMP\x03\x02\x07\x08\t\x0b\x0c\r'
>>> format.parse(b'BMP\x03\x02\x07\x08\t\x0b\x0c\r')
Container(signature=b'BMP')(width=3)(height=2)(pixels=[7, 8, 9, 11, 12, 13])

A Sequence is a collection of ordered fields, and differs from Array and GreedyRange in that those two are homogenous:

>>> format = Sequence(PascalString(Byte, "utf8"), GreedyRange(Byte))
>>> format.build([u"lalaland", [255,1,2]])
b'\nlalaland\xff\x01\x02'
>>> format.parse(b"\x004361789432197")
['', [52, 51, 54, 49, 55, 56, 57, 52, 51, 50, 49, 57, 55]]

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page