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.

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.

About#

License#

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

Additionally, you may not pretend that you wrote this software. If you use it inside a program, or if you distribute code generated by it in a program or in a library, you must acknowledge somewhere in your documentation that you have used the litgen project.

Support the project#

litgen is a free and open-source project, and its development and maintenance require considerable efforts.

If you find it valuable for your work – especially in a commercial enterprise or a research setting – please consider supporting its development by making a donation. Your contributions are greatly appreciated!

Technical Support#

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

If you need help when working in an Open Source context, please open an issue in the repository. If you need help in a professional setting, please contact the author by email, for possible consulting work.

Contributing#

Contributions and skilled contributors are welcome!

Credits#

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). srcML is published under the GNU General Public License, version 3.

Table of contents#