pybind11-weaver 0.0.1

A fully customizable pybind11 generator to help generate code for exsiting c/c++ library.

Pybind11 Weaver: Python Binding Code Generator

Pybind11 Weaver is a powerful code generator designed to automate the generation of pybind11 code from C++ header files. It streamlines the process of creating Python bindings, enabling users to focus on writing critical pybind11 code and offloading the tedious work to Pybind11 Weaver.

This tool takes a sample.h file and transforms it into a sample.cc.inc file using cfg.yaml as a guide. Following the binding with a single line auto update_guard = DeclFn(m); in binding.cc, all elements from the header file become accessible in Python as demonstrated in this example.

Key Features

1. Highly Customizable: While the default configuration is super simple and suitable for most cases, it allows for high customization.
2. Ease of Use: As a pure Python package, a simple pip install gets it ready to work.
3. Versatility: It supports the merging of generated code with hand-written code, a practice we highly recommend.
4. Structure Preservation: It retains the module structure of the original C++ code.

Features & Roadmap

• Namespace hierarchy to Python submodules
• Enum
• Enum doc
• Function, function overload
• Function doc
• Class method, method overloading, static method, static method overloading, constructor, constructor overloading
• Class field
• Class access control
• Trampoline class for virtual function
• Class doc, method doc, field doc
• Support working with hand-written code
• Auto snake case

Background & Recommendations

This project originated from an internal project aimed at creating a Python binding for a LARGE developing C++ library. This posed significant challenges:

1. The C++ library interface contained a vast number of classes, functions, and enums. Creating bindings for all these elements was not only tedious but also error-prone.
2. Because the C++ library was under active development, staying updated with daily additions and frequent code modifications was a maintenance challenge.
3. Some aspects of the C++ library, due to historical reasons, were incompatible with Python conventions, necessitating hand-written binding codes.
4. The sheer size of the library added to the complexity, making it difficult to develop a generator smart enough to handle everything, hence the need for manual binding code writing.

In light of these challenges, we designed Pybind11 Weaver as a tool to generate the majority of the binding code, leaving users to handcraft the remaining parts as needed. If this approach suits your needs, this tool will be a valuable asset.

Recommended Usage:

1. Create a cfg.yaml file to describe what needs to be generated.
2. Use the generator to create inc files.
3. Create a binding.cc, include all the inc files, and call all the binding code.
4. Compile all code into a binary to finish.
5. Optionally, use pybind11-stubgen to generate .pyi stub files, enhancing readability for both humans and MYPY in a static way.

Installation

Via PYPI

python3 -m pip install pybind11-weaver

From Source

• To install from source:

git clone https://github.com/edimetia3d/pybind11_weaver
python3 -m pip install $(pwd)/pybind11_weaver/

• To run from source (Editable/Develop Mode):

git clone https://github.com/edimetia3d/pybind11_weaver
python3 -m pip install -e $(pwd)/pybind11_weaver/ -v --config-settings editable_mode=compat