Hachoir

3.3.0 · active · verified Wed Apr 15

Hachoir is a Python library designed to view and edit binary streams field by field. It represents a binary file as a hierarchical tree of Python objects, enabling detailed analysis and manipulation down to the bit level. The current version is 3.3.0, released on December 12, 2023. The project maintains an active, though not strictly frequent, release cadence, with previous major updates in 2022 and 2020.

Warnings

breaking Hachoir 3.x is a significant rewrite, dropping Python 2 support entirely. Code written for Hachoir 2.x (Python 2) will not run on Hachoir 3.x. Additionally, earlier Hachoir sub-packages (e.g., `hachoir-core`, `hachoir-parser`) were merged into a single `hachoir` module.
Fix: Migrate Python 2 code to Python 3. For imports, consolidate from individual sub-packages (e.g., `from hachoir_parser import createParser`) to the unified `hachoir` module (e.g., `from hachoir.parser import createParser`).
breaking Hachoir 3.x requires Python 3.6 or newer. Running on older Python 3 versions (e.g., 3.4, 3.5) will result in errors.
Fix: Ensure your environment uses Python 3.6 or a more recent version. Upgrade your Python interpreter if necessary.
gotcha Hachoir operates at the bit level, not byte level, for addresses and sizes. This means that functions expecting lengths often require values in bits (e.g., `8 * bytes`) rather than raw byte counts, which can lead to off-by-eight errors or unexpected behavior if not accounted for.
Fix: Always remember that internal positions and sizes in Hachoir are measured in bits. Multiply byte counts by 8 when specifying sizes or offsets if a bit-level value is expected.
gotcha Hachoir uses lazy loading; fields are not fully parsed, and their values are not read until they are explicitly accessed (e.g., `field.value`). This design makes opening large files very fast but can be surprising for users expecting an immediate, complete parse tree.
Fix: Be aware that accessing a field's `value` or `display` attribute triggers its parsing. If you need to ensure all relevant fields are parsed or available, explicitly iterate through them or access their properties.

Install

pip install hachoir Basic Installation
pip install hachoir[urwid] For hachoir-urwid CLI tool
pip install hachoir[wx] For hachoir-wx GUI tool (Linux users may need to install wxPython via system package manager)

Imports

createParser
```
from hachoir.parser import createParser
```

extractMetadata

from hachoir.metadata import extractMetadata

StringInputStream

from hachoir.stream import StringInputStream

FileInputStream

from hachoir.stream import FileInputStream

LITTLE_ENDIAN
wrong:
```
from hachoir.core.endian import LITTLE_ENDIAN
```
correct:
```
from hachoir.stream import LITTLE_ENDIAN
```
While `hachoir.core.endian` is the source, examples commonly import `LITTLE_ENDIAN` directly from `hachoir.stream`.

Quickstart

This quickstart demonstrates how to define a simple custom parser, create an in-memory `StringInputStream` from binary data, and then parse and access fields using Hachoir. It illustrates the basic workflow of defining field types and accessing their values.

import io
from hachoir.stream import StringInputStream, LITTLE_ENDIAN
from hachoir.field import Root, UInt8, UInt16, Bytes
from hachoir.parser import Parser

# Define a simple custom parser for demonstration
class SimpleBinaryParser(Parser):
    PARSER_TAGS = {
        "id": "simple_bin",
        "category": "misc",
        "description": "Simple binary format"
    }
    endian = LITTLE_ENDIAN # Specify endianness for the parser

    def createFields(self):
        # A 1-byte header identifier
        yield UInt8(self, "header_byte", "Header identifier")
        # A 2-byte unsigned integer for length (little endian)
        yield UInt16(self, "length", "Length of data section")
        # A data payload whose size is determined by the 'length' field
        yield Bytes(self, "data", self["length"].value, "Data payload")

# Create a dummy binary string:
# - 0xAA (1 byte) for 'header_byte'
# - 0x05 0x00 (2 bytes, little endian representation of 5) for 'length'
# - "hello" (5 bytes) for 'data'
dummy_data = b"\xAA\x05\x00hello"

# Create a StringInputStream from the dummy data
stream = StringInputStream(dummy_data, "simple_data_stream")

# Instantiate the parser with the stream
parser = SimpleBinaryParser(stream)

# Access and print the parsed field values
print(f"Parsed Header Byte: {parser['header_byte'].value} (0x{parser['header_byte'].value:02X})")
print(f"Parsed Length: {parser['length'].value}")
print(f"Parsed Data: {parser['data'].value.decode('ascii')}")

view raw JSON →