litgen C++ Python bindings contributor

You are an expert contributor to **litgen**, a C++→Python bindings generator built on srcML. This tool generates pybind11 or nanobind bindings from C++ headers with high-fidelity documentation transfer.

What litgen does

- C++ binding code (compiled into Python extension)

- Python stub files (.pyi) with accurate signatures and documentation

Project structure

Python packages (under `src/`)

- Key files: `options.py`, `litgen_generator.py`, `cli/`, `integration_tests/`

- Key file: `amalgamated_header.py` (see Amalgamation section)

- Key files: `cli/srcmlcpp_cli.py`, `srcml_wrapper.py`

CLI scripts (in `pyproject.toml`)

Development workflow

Setup (Python ≥ 3.10 required)

```bash

Create virtual environment, then:

just install_requirements_dev

just install_litgen_editable

```

Code quality checks

```bash

just black # Format code

just mypy # Type checking

just ruff # Linting

Run all checks (mypy/black/ruff/pytest)

./ci_scripts/devel/run_all_checks.sh

```

Build documentation

```bash

just docs # Builds JupyterBook → litgen-book/

```

Testing

Integration tests

Location: `src/litgen/integration_tests/` (mylib example)

```bash

Test pybind11 backend

just integration_tests_pybind

Test nanobind backend

just integration_tests_nanobind

Test both backends

just integration_tests

```

Backend selection

Control via environment variable:

Pytest configuration

Targets in `pytest.ini`: `src/litgen`, `src/codemanip`, `src/srcmlcpp`

Amalgamation (multi-header APIs)

When classes span multiple headers, inherited members can be missed. Generate a single amalgamation header:

```python

from codemanip.amalgamated_header import write_amalgamate_header_file, AmalgamationOptions

write_amalgamate_header_file(AmalgamationOptions(

base_dir="path/to/headers",

local_includes_startwith="myproject/",

include_subdirs=True,

main_header_file="main.h",

dst_amalgamated_header_file="amalgamated.h"

))

```

See `litgen-book/02_05_10_amalgamation.md` for examples.

srcML parsing gotchas

To ensure clean parsing:

1. **Avoid default params like `={}`** — use concrete values (`= 0`)

2. **Don't mix API visibility markers with `auto` return types** — parsing breaks

3. **Arrow returns** (`auto f(...) -> T`) map to Python annotations

4. **Inferred `auto` returns** become `typing.Any`

Full details: `litgen-book/12_05_00_srcml_issues.md`

Code conventions

Packaging

CI expectations

Workflow `.github/workflows/pip.yml` runs on macOS/Ubuntu/Windows:

```bash

just install_requirements_dev

just install_litgen_editable

just black

just mypy

Integration tests for both backends

```

Where to implement changes

New generator features

Code manipulation helpers

srcML integration/CLI

Testing requirement

All changes must keep both pybind11 and nanobind flows passing (`just integration_tests`)

Documentation

Contributing guidelines

1. Run all checks before committing: `./ci_scripts/devel/run_all_checks.sh`

2. Ensure both backend integration tests pass

3. Update relevant documentation in `litgen-book/`

4. Follow Black/Ruff/Mypy standards (enforced by CI)

5. Add tests for new features in appropriate test directories

When implementing changes, always verify against both pybind11 and nanobind backends to maintain compatibility.