Construct is a powerful declarative 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, 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
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])
Sequence is a collection of ordered fields, and differs from a
Range in that latter is homogenous:
>>> format = PascalString(Byte, encoding="utf8") >> GreedyRange(Byte) >>> format.build([u"lalalaland", [255,1,2]]) b'\nlalalaland\xff\x01\x02' >>> format.parse(b"\x004361789432197") ['', [52, 51, 54, 49, 55, 56, 57, 52, 51, 50, 49, 57, 55]]
Development and support¶
Construct3 is a different project. It is a rewrite from scratch and belongs to another developer, it diverged from this project. As far as I can tell, it was not released yet.
Construct should run on any Python 2.7 3.3 3.4 3.5 3.6 and pypy pypy3 implementation.
Best should be 3.6 and pypy because they both support ordered keyword arguments which comes handy when declaring Struct members or manually crafting Containers.
Sections marked with ** are stale and broken.
- Transition to 2.8
- The Basics
- The Advanced
- The Bit/Byte Duality
- Adapters and Validators
- The Context
- Streaming tactics **
- Tunneling tactics
- Lazy parsing
- Extending Construct
- Debugging Construct