regenerate-bindings

---
name: regenerate-bindings
description: Regenerate Python bindings after modifying C++ headers that have Python bindings. Invoke after editing headers in external/*/src/ or external/hello_imgui/hello_imgui/src/ that affect the Python API.
---

# Regenerate Python Bindings

After modifying C++ header files that are exposed to Python (e.g., `app_window_params.h`, `runner_params.h`, `imgui.h`, etc.), you MUST regenerate the bindings using litgen. **Never hand-edit generated files.**

## Entry points

- Recipes: `libs_bindings <lib>`, `libs_bindings_all`; then `mypy`, `mypy_bindings_scripts` (the generator scripts) and `test_pytest`.
- Docs: in the next section.

## Essential developer documentation

Before working on bindings, read the relevant developer docs in `docs/book/devel_docs/`:

- **`bindings_intro.md`** — How the litgen-based generation system works, folder structure, configuration
- **`bindings_update.md`** — Step-by-step workflow for updating bindings after changes (the primary reference)
- **`bindings_forks.md`** — Fork model, branch conventions (`imgui_bundle` branch), rebase workflow, `[ADAPT_IMGUI_BUNDLE]` markers
- **`bindings_newlib.md`** — Adding new libraries; also documents Python compatibility patterns (`#ifdef IMGUI_BUNDLE_PYTHON_API`, replacing pointers with vectors, etc.)
- **`structure.md`** — Repository folder structure and architecture layers

Read these docs when you need deeper understanding. They contain the authoritative workflows.

## Generated files (DO NOT edit manually)

- `bindings/imgui_bundle/*.pyi` (Python stubs)
- `external/*/bindings/pybind_*.cpp` (C++ nanobind code)
- `external/hello_imgui/bindings/hello_imgui_amalgamation.h`

Autogenerated code is between `<litgen_pydef>`/`</litgen_pydef>` and `<litgen_stub>`/`</litgen_stub>` markers. Code outside these markers may be edited manually.

## How to regenerate


```bash
just libs_bindings lib_name
```

### After regeneration

1. Check `git diff --stat` to verify only expected files changed
2. Review the diff to confirm only your new fields/functions appear
3. If you see unexpected enum renames or other spurious changes, revert and use `just libs_bindings_all` instead

## Reading the regeneration log

`just libs_bindings_all` logs are dominated by `\r`-overwritten progress lines. To find the real warnings:

```bash
tr '\r' '\n' < log | grep 'Warning: ('
```

## The `.pyi` preamble is hand-editable (and partly hand-maintained)

Each `bindings/imgui_bundle/<lib>/*.pyi` has a **preamble before the `<litgen_stub>` marker** (imports, module notes) that litgen **preserves across regeneration**. This is the right place for module-level notes. Crucially, the `from imgui_bundle.imgui import (...)` block at the top of `internal.pyi` is **hand-maintained**, not auto-generated: litgen does not add cross-module imports for you. (Misreading it as auto-generated leads to a wrong "litgen bug" conclusion.)

## Binding or suppressing `ImVector<T>` types

When an imgui update adds a new `ImVector<T>` member (e.g. `ImGuiContext::FontAtlases`, new in v1.92), litgen warns: `Excluding template type ImVector<T> ...`. Decide bind-or-suppress:

- **Bind it**: add `"T"` (e.g. `"ImFontAtlas*"`) to `instantiated_types` in `external/imgui/bindings/litgen_options_imgui.py` (`_add_imvector_template_options`). If the type is used in `internal.pyi`, you must **also** add `ImVector_<T>` to that file's import preamble (see above), or pre-commit ruff fails with `F821`. Naming: litgen strips `ImGui` and maps `*`→`_ptr` (`ImGuiWindow*`→`ImVector_Window_ptr`, but `ImFontAtlas*`→`ImVector_ImFontAtlas_ptr`).
- **Suppress it** (opaque/internal element type, not bindable): add it to `ignored_types` in the same function (auto-generates the suppression). For one-off warnings in any library, use `options.srcmlcpp_options.ignored_warning_parts += ["substring of the warning"]` (substring match) in that library's `generate_*.py`. Examples: `operator=` (no Python equivalent), opaque stb types (`stbrp_node_im`).

A regenerated member is not usable at runtime until the C++ `_imgui_bundle` module is rebuilt (the `.pyi`/pydef are source only).

## About litgen

Litgen (Literate Generator) is the tool that generates Python bindings from C++ headers. It parses C++ using srcML and generates both nanobind C++ code and `.pyi` stubs.

- **Litgen docs**: https://pthom.github.io/litgen (also in `docs/litgen_book` of a litgen checkout, e.g. `../litgen`, next to the bundle)
- **Litgen source**: https://github.com/pthom/litgen (or the checkout `../litgen`)
- **Options reference**: `src/litgen/options.py` in litgen

Each library has its own generator script with litgen options:
- `external/<lib>/bindings/generate_<lib>.py` — configures `LitgenOptions` for that library
- `external/bindings_generation/autogenerate_all.py` — master script that calls all generators

When bindings don't generate as expected (wrong naming, missing functions, excluded types), check the `LitgenOptions` in the library's `generate_*.py` script. Common options include function/class renames, type replacements, and exclusion patterns.

## Adapting C++ for Python compatibility

When a C++ API uses patterns incompatible with Python bindings, use preprocessor guards in the forked library:

- `#ifdef IMGUI_BUNDLE_PYTHON_API` — code compiled only for Python bindings
- `#ifdef IMGUI_BUNDLE_PYTHON_UNSUPPORTED_API` — code excluded from Python

Common adaptations (bracket with `// [ADAPT_IMGUI_BUNDLE]` markers):
- Replace `pointer + count` with `std::vector<T>`
- Replace C function pointers with `std::function`
- Replace `const char*` with `std::optional<std::string>`
- Exclude `void* user_data` from Python callbacks

## Hello ImGui documentation

Hello ImGui also has autogenerated doc files (`doc_params.md`, `doc_api.md`), generated from `.src.md` sources by `tools/doc/process_md_docs.py`. These are gitignored — CI regenerates them automatically before building the online docs.

More agent context in pthom/imgui_bundle

7 other files this repository gives its agents.