Metadata-Version: 2.1
Name: pybind11_weaver
Version: 0.0.1
Summary: A fully customizable pybind11 generator to help generate code for exsiting c/c++ library.
License: MIT
Keywords: pybind11,generator,codegen,gen
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Description-Content-Type: text/markdown
License-File: LICENSE

# 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](sample/enum/sample.h) file and transforms it into a [sample.cc.inc](sample/enum/sample.cc.inc) file using [cfg.yaml](sample/enum/cfg.yaml) as a guide. Following the binding with a single line `auto update_guard = DeclFn(m);` in [binding.cc](sample/enum/binding.cc), all elements from the header file become accessible in Python as demonstrated in this [example](test/sample_test/launch_module.py).


## 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
- [x] Namespace hierarchy to Python submodules
- [x] Enum
- [ ] Enum doc
- [x] Function, function overload
- [ ] Function doc
- [x] Class method, method overloading, static method, static method overloading, constructor, constructor overloading
- [x] Class field
- [x] 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](https://github.com/sizmailov/pybind11-stubgen) to generate `.pyi` stub files, enhancing readability for both humans and MYPY in a static way.

## Installation

### Via PYPI

```bash
python3 -m pip install pybind11-weaver
```

### From Source

* To install from source:

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

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

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