Metadata-Version: 2.4
Name: headerkit
Version: 0.6.1
Summary: C/C++ header analysis toolkit with pluggable backends and writers for ctypes, Cython, CFFI, LuaJIT FFI, and more
Project-URL: Homepage, https://github.com/axiomantic/headerkit
Project-URL: Repository, https://github.com/axiomantic/headerkit
Project-URL: Issues, https://github.com/axiomantic/headerkit/issues
Project-URL: Changelog, https://github.com/axiomantic/headerkit/blob/main/CHANGELOG.md
Author-email: elijahr <elijahr+cir@gmail.com>
License-Expression: MIT AND Apache-2.0 WITH LLVM-exception
License-File: LICENSE
License-File: headerkit/_clang/LICENSE
Keywords: c,c++,cffi,code-generation,ir,libclang,parser
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: C
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mike>=2.1; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-timeout; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mike>=2.1; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-timeout; extra == 'test'
Description-Content-Type: text/markdown

# headerkit

[![CI](https://github.com/axiomantic/headerkit/actions/workflows/ci.yml/badge.svg)](https://github.com/axiomantic/headerkit/actions/workflows/ci.yml)
[![Docs](https://github.com/axiomantic/headerkit/actions/workflows/docs.yml/badge.svg)](https://axiomantic.github.io/headerkit/)
[![PyPI](https://img.shields.io/pypi/v/headerkit)](https://pypi.org/project/headerkit/)
[![Python](https://img.shields.io/pypi/pyversions/headerkit)](https://pypi.org/project/headerkit/)

A general-purpose C/C++ header analysis toolkit with a pluggable architecture. Parse once with libclang, output to any format through 7 built-in writers.

headerkit carries the torch for [ctypesgen2](https://github.com/ctypesgen/ctypesgen) as a ctypes binding generator and serves as the new engine behind [autopxd2](https://github.com/elijahr/autopxd2) for Cython .pxd generation.

Full documentation: [axiomantic.github.io/headerkit](https://axiomantic.github.io/headerkit/)

## Architecture

headerkit separates parsing from output generation. A parser backend (currently libclang) produces a language-neutral IR (intermediate representation), and any number of writers consume that IR to generate output. Add a backend, and all writers benefit. Add a writer, and all backends feed it.

```
C/C++ headers --> [libclang backend] --> IR --> [writer] --> output
```

## Writers

| Writer | Output | Description |
|--------|--------|-------------|
| **cffi** | CFFI cdef strings | Declarations for `ffibuilder.cdef()` |
| **ctypes** | Python modules | Complete ctypes binding modules (successor to ctypesgen2) |
| **cython** | .pxd files | Cython declaration files with C++ support (ported from autopxd2) |
| **diff** | JSON or Markdown | API compatibility reports between header versions |
| **json** | JSON | Full IR serialization for inspection and tooling |
| **lua** | LuaJIT FFI bindings | `ffi.cdef()` declarations for LuaJIT |
| **prompt** | Compact text | Token-optimized IR output for LLM context windows |

## Installation

Requires Python 3.10+. Zero Python package dependencies (nothing extra pulled from PyPI).

```bash
pip install headerkit
```

## System Requirements

libclang shared library must be installed:

- macOS: `brew install llvm` or Xcode Command Line Tools
- Ubuntu: `sudo apt install libclang-dev`
- Fedora: `sudo dnf install clang-devel`
- Windows: Download the [LLVM installer](https://github.com/llvm/llvm-project/releases) or `winget install LLVM.LLVM`

Or use the bundled installer:

```bash
headerkit-install-libclang
```

Supports LLVM 18, 19, 20, and 21. The appropriate version is detected automatically.

## Usage

Parse a header and generate output with any writer:

```python
from headerkit.backends import get_backend
from headerkit.writers import get_writer

backend = get_backend("libclang")
header = backend.parse('#include "mylib.h"', "wrapper.h", include_dirs=["/path/to/include"])

# CFFI bindings
cffi_writer = get_writer("cffi")
print(cffi_writer.write(header))

# ctypes bindings
ctypes_writer = get_writer("ctypes")
print(ctypes_writer.write(header))

# Cython .pxd
cython_writer = get_writer("cython")
print(cython_writer.write(header))

# JSON for tooling
json_writer = get_writer("json")
print(json_writer.write(header))
```

List available writers:

```python
from headerkit.writers import list_writers
print(list_writers())  # ['cffi', 'ctypes', 'cython', 'diff', 'json', 'lua', 'prompt']
```

## Development

```bash
git clone https://github.com/axiomantic/headerkit.git
cd headerkit
pip install -e '.[dev]'
pytest
```

## License

This project is licensed under the [MIT License](LICENSE).

The vendored clang Python bindings in `headerkit/_clang/v*/` are from the
[LLVM Project](https://llvm.org/) and are licensed under the
[Apache License v2.0 with LLVM Exceptions](headerkit/_clang/LICENSE).
