Registry / serialization / kaitaistruct

kaitaistruct

JSON →
library0.11pypypi✓ verified 25d ago

Kaitai Struct provides a declarative parsing framework for binary data. This library serves as the Python runtime component, allowing users to load and interpret binary files based on `.ksy` specifications compiled into Python classes. The current version is 0.11, and releases are generally stable, focusing on compatibility with the Kaitai Struct compiler.

pip install kaitaistruct
INSTALL
IMPORT
SIG · KAITAISTRUCT
K
kaitaistruct
serializationpythonv0.11
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

KaitaiStream
from kaitaistruct import KaitaiStream
import kaitaistruct.KaitaiStream
KaitaiStream is the primary class for wrapping binary data for parsing.
KaitaiStruct
from kaitaistruct import KaitaiStruct
from kaitaistruct.core import KaitaiStruct
Base class for all generated Kaitai Struct parsers.
GeneratedParserClass
from my_parser import MyParserClass
Most commonly, users import classes from their *generated* Python modules (e.g., my_parser.py), not directly from the kaitaistruct package.

To use `kaitaistruct`, you first need to define your binary format in a `.ksy` (Kaitai Struct YAML) file. Then, use the **Kaitai Struct Compiler (ksc)** (a separate, Java-based tool available from `kaitai.io`) to generate the Python parsing code. The `ksc` command `ksc --target python your_spec.ksy` will produce `your_spec.py`. Once generated, you can import and use the classes from this file to parse your binary data. The example below *simulates* a generated class for demonstration purposes, assuming a `test.ksy` parsing a little-endian 4-byte integer.

import os # Assuming 'test.py' was generated from 'test.ksy' by the ksc compiler. # The 'test.ksy' and 'test.bin' files would typically be created externally. # For this runnable example, we'll create them in a temporary manner. # 1. Create a dummy binary file to parse binary_data = b'\x01\x02\x03\x04' with open('test.bin', 'wb') as f: f.write(binary_data) print(f"Created test.bin with data: {binary_data.hex()}") # 2. Simulate the presence of a generated parser class 'Test' # In a real scenario, this would come from `ksc --target python test.ksy` # and you'd simply `from test import Test`. # For this example, we mock the class directly. from kaitaistruct import KaitaiStream, KaitaiStruct class Test(KaitaiStruct): def __init__(self, _io, _parent=None, _root=None): self._io = _io self._parent = _parent self._root = _root if _root else self self._read() def _read(self): self.my_field = self._io.read_u4le() @property def get_my_field(self): return self.my_field # 3. Use the generated (or mocked) parser to read the binary data with open('test.bin', 'rb') as f_obj: io_stream = KaitaiStream(f_obj) parsed_data = Test(io_stream) print(f"Parsed value: {parsed_data.my_field} (0x{parsed_data.my_field:x})") # Clean up generated/dummy files os.remove('test.bin')
Debug
Known issues
gotchaThe `kaitaistruct` Python library is a *runtime* component. It does not perform the code generation itself. You MUST use the separate, Java-based Kaitai Struct Compiler (`ksc`) to convert your `.ksy` specifications into Python code before you can use this library.
fix
Download and install the `ksc` compiler from `https://kaitai.io/` or via a package manager (e.g., `brew install kaitai-struct-compiler`). Then run `ksc --target python your_spec.ksy` to generate your parser module.
affects: All versions
gotchaGenerated Python parser files (e.g., `my_parser.py`) must be discoverable by Python's import mechanism. If you get `ModuleNotFoundError`, it's likely Python cannot find the generated module.
fix
Ensure the generated `.py` file is in the same directory as your script, or that its directory is on your `PYTHONPATH`. For projects, consider packaging generated files or placing them in a designated source directory.
affects: All versions
breakingMajor internal changes occurred between Kaitai Struct compiler/runtime versions 0.9 and 0.10, particularly affecting how `_parent` and `_root` contexts are handled in `.ksy` specifications. Older specifications might fail or produce incorrect results with newer runtimes.
fix
Review and update your `.ksy` specifications for compatibility with Kaitai Struct 0.10+ if you are experiencing parsing issues with complex structures. Consult the Kaitai Struct release notes for detailed migration steps.
affects: Specifications targeting <0.10 used with >=0.10 runtime/compiler
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'kaitaistruct'
The `kaitaistruct` Python runtime library is not installed in the environment where the code is being executed.
fix
Install the library using pip: `pip install kaitaistruct`
YAMLParseException: ... unknown key found, expected: ...
The `.ksy` (Kaitai Struct YAML) specification file contains incorrect YAML syntax or uses keys that are not recognized by the Kaitai Struct compiler.
fix
Review the `.ksy` file for typos, incorrect indentation, or misplacement of keys. Consult the Kaitai Struct documentation and KSY syntax diagram to ensure correct structure and valid keys for the specified context.
EOFError: requested to read X bytes, but only Y bytes left in the stream
The Kaitai Struct parser attempted to read more bytes than were available in the input stream, indicating a mismatch between the `.ksy` specification and the actual binary data structure, or an corrupted/truncated input file.
fix
Verify that your `.ksy` specification accurately describes the binary data format. Use the Kaitai Struct Web IDE or visualizer to debug the parsing process and compare the expected structure with the input data. Ensure the input file is complete and not corrupted.
AttributeError: type object 'KaitaiStream' has no attribute 'eof'
This error typically indicates a version mismatch between the Python code generated by the Kaitai Struct compiler and the installed `kaitaistruct` Python runtime library.
fix
Ensure that the `kaitaistruct` runtime library version is compatible with the version of the Kaitai Struct compiler used to generate your Python parser classes. Upgrade or downgrade the `kaitaistruct` package if necessary (e.g., `pip install --upgrade kaitaistruct` or `pip install kaitaistruct==0.X`).
Upgrade
Version history
0.11latest on PyPI · released Sep 8, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
6
Resources
kaitaistruct — pip install kaitaistruct · libregistry