Litgen

Automatic Python bindings for C++: readable, discoverable, IDE-friendly.
Battle-tested on 20+ libraries and 100,000 lines of code. Because your users deserve bindings they can actually read.

litgen generates Python bindings for C++ libraries using pybind11 or nanobind. It can also be used as a C++ transformation and refactoring tool. Source code, Documentation, PyPI

litgen is the main driving force behind the Python bindings for Dear ImGui Bundle. It puts a strong emphasis on emitting documented and discoverable code, providing a great experience for the final Python user.

Documented bindings¶

As an intro, here is an example when using bindings generated by litgen inside a python Integrated Development Environment (IDE):

Example of auto-completion in an IDE: all bindings are discoverable

Parameters type are accurately reproduced, and the function documentation is accessible

In the example above, the bindings were generated from the following C++ function signature:

// Parameters stacks (current window)
IMGUI_API void          PushItemWidth(float item_width); // push width of items for common large "item+label" widgets. >0.0f: width in pixels, <0.0f align xx pixels to the right of window (so -FLT_MIN always align width to the right side).

And the generated code consists of two parts:

a python stub file, which contains the documentation and the function signatures, e.g.:

# Parameters stacks (current window)
# IMGUI_API void          PushItemWidth(float item_width);        /* original C++ signature */
def push_item_width(item_width: float) -> None:
    """push width of items for common large "item+label" widgets. >0.0: width in pixels, <0.0 align xx pixels to the right of window (so -FLT_MIN always align width to the right side)."""
    pass

a C++ bindings file, which contains the actual bindings, e.g.:

m.def("push_item_width",
    ImGui::PushItemWidth,
    py::arg("item_width"),
    "push width of items for common large \"item+label\" widgets. >0.0: width in pixels, <0.0 align xx pixels to the right of window (so -FLT_MIN always align width to the right side).");

Examples¶

More complete examples can be found online inside the Dear ImGui Bundle repository, for example:

imgui.h header file that declares the API for Dear ImGui in a documented way
imgui.piy the corresponding python stub file which exposes the bindings in a documented way

Compatibility¶

Being based on srcML, litgen is compatible with C++14: your code can of course make use of more recent features (C++17, C++20 and C++23), but the API that you want to expose to python must be C++14 compatible.

License¶

The litgen project is published under the GNU General Public License, version 3.

Code generated by litgen is not subject to the GPL license, allowing you to use it freely in your projects without the obligations of GPLv3.

Credits¶

Acknowledging the use of litgen in your project’s documentation is a nice way to support the project and help others discover it.

litgen is based on srcML, a multi-language parsing tool that converts source code into XML with a developer-centric approach: preprocessor statements are kept unprocessed, and all original text is preserved (including whitespace, comments, and special characters). srcML is published under the GNU General Public License, version 3.

Keep in Touch¶

We’d love to hear about how you’re using litgen! If you are using it, please consider sharing your experience and insights.

Contributing¶

Contributions and skilled contributors are welcome! See contributors oriented documentation inside Build.md.

Help the Project¶

If litgen has made a difference for you - especially in a commercial or research setting - please consider making a donation. Your support goes a long way toward keeping the project alive and growing. Any contribution, no matter the size, is greatly appreciated!

Technical Support¶

C++ is notorious for being hard to parse. As a consequence, the author makes no guarantee that the generator will work on all kinds of C++ constructs.

Open Source Support: If you need assistance in an open-source context, please open an issue in the repository.

Professional Support: For more in-depth help in a professional setting, feel free to reach out to the author via email for consulting inquiries.