construct Binary Data Parser

2.10.70 · active · verified Thu Apr 09

construct is a powerful declarative symmetric parser/builder for binary data, supporting Python 3.6+. It allows you to define the structure of binary data using Python objects and then parse or build data according to that structure. The current version is 2.10.70, and it maintains a fairly active release cadence, often releasing minor fixes and improvements.

Warnings

breaking Major API overhaul occurred between construct 2.0 and 2.5/2.6. This was a near-complete rewrite, deprecating and removing many constructs (e.g., `Buffer`, `BitStruct`), changing import paths (`construct.core`), and modifying core behaviors. Code written for construct 2.0 is highly unlikely to work with 2.5+.
Fix: Migrate your code to the modern construct API (2.8+ is recommended). This will likely involve a complete rewrite of your structure definitions and parsing/building logic. Refer to the official construct documentation for the current API.
breaking Breaking changes were introduced in versions 2.8 and 2.9. Notably, `Subconstruct` was removed in 2.8 (use `Construct` directly), `RepeatUntil` was renamed to `GreedyRange`, and `Context.error_when` behavior changed slightly in 2.9.
Fix: Review the changelog for versions 2.8 and 2.9. Update `Subconstruct` usage to directly use the base construct, rename `RepeatUntil` to `GreedyRange`, and adjust conditional error handling if `Context.error_when` was used.
gotcha Construct objects (e.g., `Struct`, `Array`) are often mutable. If you create an instance of a construct and then modify its internal properties or reuse it in different contexts without care, you might encounter unexpected side effects due to shared state.
Fix: If you need to reuse a construct with different parameters or ensure isolation, create a new instance each time, or use `construct.deep_copy` if you're modifying a complex, nested structure and need a true independent copy.
gotcha The `this` (or `ctx`) variable, used for accessing context and previously parsed fields within `lambda` functions or methods, can be a source of confusion. Misunderstanding its scope or when certain fields become available can lead to errors.
Fix: Thoroughly understand the `Context` object and how `this` (or `ctx`) dynamically refers to the current parsing/building context. Debug with `construct.Probe` to inspect the context at various points in your structure definition. Ensure fields are defined before they are referenced via `this`.

Install

pip install construct Install stable version

Imports

Struct
```
from construct import Struct
```
Old import path for construct versions prior to 2.5/2.6. Modern construct uses top-level imports.
Int8ub
```
from construct import Int8ub
```
Bytes
```
from construct import Bytes
```
Array
```
from construct import Array
```
GreedyRange
```
from construct import GreedyRange
```
StreamError
```
from construct import StreamError
```

Quickstart

This quickstart demonstrates how to define a `Struct` using various constructors like `Bytes`, `Int8ub`, `Array`, and `GreedyRange`. It shows how to use lambda functions within a structure definition to refer to previously parsed fields (e.g., `ctx.count`). Finally, it illustrates building Python objects into binary data and parsing binary data back into Python objects, including basic error handling.

from construct import Struct, Int8ub, Bytes, Array, GreedyRange, StreamError

# Define a simple binary structure
# A header, an array of 8-bit unsigned integers, and a variable-length data block
packet_struct = Struct(
    "header" / Bytes(4), # 4-byte header
    "count" / Int8ub,    # 1-byte count of following integers
    "data" / Array(lambda ctx: ctx.count, Int8ub), # Array of 'count' integers
    "payload" / GreedyRange(Int8ub) # Remaining bytes as a list of integers
)

# Example data to build
my_data = {
    "header": b"\xde\xad\xbe\xef",
    "count": 3,
    "data": [10, 20, 30],
    "payload": [1, 2, 3, 4, 5]
}

# Build binary data from Python object
built_binary = packet_struct.build(my_data)
print(f"Built binary: {built_binary.hex()}")

# Parse binary data into Python object
# Using a different example binary for parsing
binary_to_parse = b"\xaa\xbb\xcc\xdd\x02\x01\x02\xff\xee\xdd"

try:
    parsed_object = packet_struct.parse(binary_to_parse)
    print(f"Parsed object: {parsed_object}")

    # Accessing fields
    print(f"Parsed header: {parsed_object.header.hex()}")
    print(f"Parsed data: {parsed_object.data}")
except StreamError as e:
    print(f"Error parsing data: {e}")

view raw JSON →