Ctrl+K

litgen

litgen#

What is litgen

litgen, also known as Literate Generator, is an automatic python bindings generator for humans who like nice code and APIs.

It can be used to bind C++ libraries into documented and discoverable python modules using pybind11 or nanobind.

It can also be used as C++ transformation and refactoring tool.

Source code, Documentation, PyPI

Although being relatively new (2022), litgen was battle tested on 20 different libraries totalling more than 100,000 lines of code, and it is the main driving force behind the python bindings for Dear ImGui Bundle.

litgen puts a strong emphasis on emitting documented and discoverable code, thus providing a great experience for the final python user.

srcML

litgen is based on srcML, a multi-language parsing tool to convert source code into XML, with a developer centric approach: preprocessor statements are kept unprocessed, and all original text is preserved (including white space, comments and special characters).

Documented bindings#

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

IDE auto completion

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

IDE params

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:

  1. 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

  1. 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.

Table of contents#

Installation

Bindings - Advanced Topics

Litgen as C++ transformation tool

Contents