pybindgen

library0.22.1pypypi✓ verified 87d ago

PyBindGen is a code generator that produces C++ source files to create Python bindings for C/C++ libraries. It helps expose C/C++ functions and classes to Python without writing manual wrapper code. As of version 0.22.1, it's an active project with a slow but steady release cadence, often tied to changes in `ns-3` (its primary consumer).

serialization

pip install pybindgen

github ↗package ↗

INSTALL

IMPORT

SIG · PYBINDGEN

pybindgen

serializationpythonv0.22.1

Install

1.6s avg

Import

50ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.22.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.051s · 19.1MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.049s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Module

✓ from pybindgen import Module

The core class to define a Python module and add C++/Python bindings.

Parameter

✓ from pybindgen import Parameter

Used to define parameters for wrapped C++ functions.

ReturnValue

✓ from pybindgen import ReturnValue

Used to define return values for wrapped C++ functions.

This quickstart demonstrates how to define a simple Python module that wraps a C++ function `add(int, int)`. The `generate_bindings` function creates a `Module` instance, adds a function definition with its parameters and return value, and then generates the C++ source file `my_bindings_module.cc`. This generated file then needs to be compiled into a Python extension module using a C++ compiler and a build system like `setuptools` or `waf`.

from pybindgen import Module, Function, Parameter, ReturnValue def generate_bindings(filename): module = Module('my_bindings_module', cpp_namespace='MyCppNamespace') # Example: Bind a simple C++ function 'int add(int a, int b);' module.add_function( 'add', retval=ReturnValue.copy(Parameter.new('int', 'a')), params=[Parameter.new('int', 'a'), Parameter.new('int', 'b')] ) # Generate the C++ binding code module.generate(filename) print(f"Generated binding code to {filename}") # To run this, you would typically integrate it into a setup.py or build script # For a standalone example: # generate_bindings('my_bindings_module.cc')

pybindgen --version

Debug

Known issues

gotchaPyBindGen only generates C++ binding code; it does not compile it. Users must have a C++ compiler (e.g., g++ or clang) and Python development headers installed to compile the generated `.cc` files into a Python extension module.

fix

Ensure `python3-dev` (Linux), `python-devel` (RHEL/CentOS), or Xcode Command Line Tools (macOS) are installed, along with a C++ compiler.

affects: All versions

gotchaThe generated C++ code needs to be integrated into a build system (e.g., `setuptools`, `waf`, `CMake`) to be compiled and linked correctly as a Python extension module. Simply generating the `.cc` file is only the first step.

fix

Refer to PyBindGen documentation or examples for integrating generated code with `setuptools` (using `Extension` and `build_ext`) or other build systems.

affects: All versions

gotchaWrapping complex C++ features like templates, custom memory management, or deep inheritance hierarchies can be challenging and may require manual adjustments or advanced PyBindGen techniques not covered in simple examples.

fix

Start with simple functions and classes. Consult PyBindGen's advanced documentation and examples for handling more complex C++ constructs. Be prepared for some manual C++ code (e.g., custom type traits or converters) if PyBindGen's automatic wrapping isn't sufficient.

affects: All versions

Errors

Common errors & fixes

fatal error: Python.h: No such file or directory

During compilation of the generated C++ binding code, the C++ compiler cannot find the Python development header files, which are essential for building Python extension modules.

fix

Install the Python development package for your system. For Debian/Ubuntu: `sudo apt-get install python3-dev`. For Fedora/RHEL: `sudo dnf install python3-devel`. For macOS with Xcode Command Line Tools, Python headers are usually available, but ensure `python3` is linked correctly.

undefined reference to `MyCppNamespace::add(int, int)`

This linker error occurs during the compilation of the generated C++ binding code. It means the linker cannot find the actual C++ function `add` (or any other function/class) that the bindings are supposed to wrap. This usually happens because the library containing the actual C++ code was not linked.

fix

Ensure that the C++ library containing `MyCppNamespace::add` (or your actual C++ code) is correctly linked against the generated binding code. If using `setuptools.Extension`, add `libraries=['mylibrary']` and `library_dirs=['/path/to/lib']` to your `Extension` definition.

ImportError: dynamic module does not define module export function (PyInit_my_bindings_module)

This runtime error typically occurs when trying to `import` the compiled Python extension module. It indicates an issue with the compiled shared library, often due to an incorrect build configuration (e.g., wrong Python ABI, incorrect entry point generation, or an old Python version being used).

fix

Verify that the generated C++ code was compiled against the correct Python version and ABI. Ensure PyBindGen's `Module` constructor's `py_init_name` (if explicitly set) matches the `PyInit_` function expected by your Python interpreter. Rebuild the module cleanly, ensuring all dependencies are met for the target Python environment.

Upgrade

Version history

0.22.1latest on PyPI · released Mar 30, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/gjcarneiro/pybindgen ↗

packagehttps://pypi.org/project/pybindgen/ ↗