{"id":1522,"library":"kaitaistruct","title":"Kaitai Struct Python Runtime","description":"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.","status":"active","version":"0.11","language":"en","source_language":"en","source_url":"https://github.com/kaitai-io/kaitai_struct_python_runtime","tags":["binary_parsing","data_structures","compiler_runtime","reverse_engineering","serialization"],"install":[{"cmd":"pip install kaitaistruct","lang":"bash","label":"Install kaitaistruct runtime"}],"dependencies":[],"imports":[{"note":"KaitaiStream is the primary class for wrapping binary data for parsing.","wrong":"import kaitaistruct.KaitaiStream","symbol":"KaitaiStream","correct":"from kaitaistruct import KaitaiStream"},{"note":"Base class for all generated Kaitai Struct parsers.","wrong":"from kaitaistruct.core import KaitaiStruct","symbol":"KaitaiStruct","correct":"from kaitaistruct import KaitaiStruct"},{"note":"Most commonly, users import classes from their *generated* Python modules (e.g., my_parser.py), not directly from the kaitaistruct package.","symbol":"GeneratedParserClass","correct":"from my_parser import MyParserClass"}],"quickstart":{"code":"import os\n\n# Assuming 'test.py' was generated from 'test.ksy' by the ksc compiler.\n# The 'test.ksy' and 'test.bin' files would typically be created externally.\n# For this runnable example, we'll create them in a temporary manner.\n\n# 1. Create a dummy binary file to parse\nbinary_data = b'\\x01\\x02\\x03\\x04'\nwith open('test.bin', 'wb') as f:\n    f.write(binary_data)\nprint(f\"Created test.bin with data: {binary_data.hex()}\")\n\n# 2. Simulate the presence of a generated parser class 'Test'\n# In a real scenario, this would come from `ksc --target python test.ksy`\n# and you'd simply `from test import Test`.\n# For this example, we mock the class directly.\n\nfrom kaitaistruct import KaitaiStream, KaitaiStruct\n\nclass Test(KaitaiStruct):\n    def __init__(self, _io, _parent=None, _root=None):\n        self._io = _io\n        self._parent = _parent\n        self._root = _root if _root else self\n        self._read()\n\n    def _read(self):\n        self.my_field = self._io.read_u4le()\n\n    @property\n    def get_my_field(self):\n        return self.my_field\n\n# 3. Use the generated (or mocked) parser to read the binary data\nwith open('test.bin', 'rb') as f_obj:\n    io_stream = KaitaiStream(f_obj)\n    parsed_data = Test(io_stream)\n    print(f\"Parsed value: {parsed_data.my_field} (0x{parsed_data.my_field:x})\")\n\n# Clean up generated/dummy files\nos.remove('test.bin')\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Generated 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Major 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.","severity":"breaking","affected_versions":"Specifications targeting <0.10 used with >=0.10 runtime/compiler"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}