Metadata-Version: 2.4
Name: awkward_kaitai
Version: 0.11.2
Summary: Kaitai Struct runtime for Awkward Arrays
Project-URL: Homepage, https://github.com/ManasviGoyal/kaitai_struct_awkward_runtime
Project-URL: Bug Tracker, https://github.com/ManasviGoyal/kaitai_struct_awkward_runtime/issues
Project-URL: Discussions, https://github.com/ManasviGoyal/kaitai_struct_awkward_runtime/discussions
Project-URL: Changelog, https://github.com/ManasviGoyal/kaitai_struct_awkward_runtime/releases
Author-email: Manasvi Goyal <mg.manasvi@gmail.com>
License-File: LICENSE
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: awkward>=2.6.5
Requires-Dist: importlib-resources
Provides-Extra: dev
Requires-Dist: construct; extra == 'dev'
Requires-Dist: pytest-cov>=3; extra == 'dev'
Requires-Dist: pytest>=6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-jupyter; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Provides-Extra: test
Requires-Dist: construct; extra == 'test'
Requires-Dist: pytest-cov>=3; extra == 'test'
Requires-Dist: pytest>=6; extra == 'test'
Description-Content-Type: text/markdown

# Kaitai Struct: Awkward Array runtime

This project bridges Kaitai Struct schemas to Awkward Arrays. It provides a C++
runtime plus Python helpers so Kaitai-generated parsers can emit Awkward Array
buffers directly.

## Quickstart

1) Generate C++ from a `.ksy` schema using the Kaitai compiler with the Awkward target.
2) Build a shared library from the generated `.cpp`.
3) Load binary data into an Awkward Array.

Example flow:

```bash
# From a schema (requires kaitai-struct-compiler with awkward target)
java -cp <classpath> io.kaitai.struct.JavaMain -t awkward --outdir test_artifacts example_data/schemas/hello_world.ksy

# Build a shared library from the generated C++ file
awkward-kaitai-build test_artifacts/hello_world.cpp -b build
```

```python
from awkward_kaitai import Reader

reader = Reader("test_artifacts/libhello_world.so")
array = reader.load("example_data/data/hello_world.bin")
print(array)
```

## Documentation

The documentation is available at <https://det-lab.github.io/kaitai_struct_awkward_runtime/>.

## Requirements

- Kaitai Struct compiler **0.11+** with the `awkward` target.
- CMake and a C++ toolchain for building shared libraries.

## Development

- Build and test everything: `make test`
- Fast loop for a single schema: `make compile_test testcase=hello_world`
- Linting and checks: `nox -s lint` / `nox -s pylint` / `nox -s tests`
- Submodule setup: `git submodule update --init --recursive`

See `AGENTS.md` for detailed contributor guidance.

## Related Papers and Talks
1. [Describe Data to get Science-Data-Ready Tooling: Awkward as a Target for Kaitai Struct YAML](https://indico.cern.ch/event/1330797/contributions/5796564/), Advanced Computing and Analysis Techniques for Physics Research Workshop 2024, New York, US.
2. [Awkward Target for Kaitai Struct](https://indico.cern.ch/event/1252095/contributions/5592420/), PyHEP Users Workshop 2023.
