A fully customizable pybind11 generator to help generate code for exsiting c/c++ library.
Project description
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
- Highly Customizable: While the default configuration is super simple and suitable for most cases, it allows for high customization.
- Ease of Use: As a pure Python package, a simple
pip install
gets it ready to work. - Versatility: It supports the merging of generated code with hand-written code, a practice we highly recommend.
- 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:
- 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.
- Because the C++ library was under active development, staying updated with daily additions and frequent code modifications was a maintenance challenge.
- Some aspects of the C++ library, due to historical reasons, were incompatible with Python conventions, necessitating hand-written binding codes.
- 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:
- Create a
cfg.yaml
file to describe what needs to be generated. - Use the generator to create
inc
files. - Create a
binding.cc
, include all theinc
files, and call all the binding code. - Compile all code into a binary to finish.
- 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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pybind11_weaver-0.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5f1e80913009bfb4fb87a99410886fd2418e891f22cd719f553c8dbf45125ce1 |
|
MD5 | 86829a16d88ddd74716337276f2dd2a1 |
|
BLAKE2b-256 | 5c4c6ce8aa9675a4f897c03aed0bf7ac0a8835eedf76af406be5dead974cfd72 |