{"id":10082,"library":"pybindgen","title":"PyBindGen","description":"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).","status":"active","version":"0.22.1","language":"en","source_language":"en","source_url":"https://github.com/gjcarneiro/pybindgen","tags":["bindings","c++","code generation","extension modules","ffi"],"install":[{"cmd":"pip install pybindgen","lang":"bash","label":"Install PyBindGen"}],"dependencies":[],"imports":[{"note":"The core class to define a Python module and add C++/Python bindings.","symbol":"Module","correct":"from pybindgen import Module"},{"note":"Used to define parameters for wrapped C++ functions.","symbol":"Parameter","correct":"from pybindgen import Parameter"},{"note":"Used to define return values for wrapped C++ functions.","symbol":"ReturnValue","correct":"from pybindgen import ReturnValue"}],"quickstart":{"code":"from pybindgen import Module, Function, Parameter, ReturnValue\n\ndef generate_bindings(filename):\n    module = Module('my_bindings_module', cpp_namespace='MyCppNamespace')\n\n    # Example: Bind a simple C++ function 'int add(int a, int b);'\n    module.add_function(\n        'add',\n        retval=ReturnValue.copy(Parameter.new('int', 'a')),\n        params=[Parameter.new('int', 'a'), Parameter.new('int', 'b')]\n    )\n\n    # Generate the C++ binding code\n    module.generate(filename)\n    print(f\"Generated binding code to {filename}\")\n\n# To run this, you would typically integrate it into a setup.py or build script\n# For a standalone example:\n# generate_bindings('my_bindings_module.cc')","lang":"python","description":"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`."},"warnings":[{"fix":"Ensure `python3-dev` (Linux), `python-devel` (RHEL/CentOS), or Xcode Command Line Tools (macOS) are installed, along with a C++ compiler.","message":"PyBindGen 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to PyBindGen documentation or examples for integrating generated code with `setuptools` (using `Extension` and `build_ext`) or other build systems.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Wrapping 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"fatal error: Python.h: No such file or directory"},{"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.","cause":"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.","error":"undefined reference to `MyCppNamespace::add(int, int)`"},{"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.","cause":"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).","error":"ImportError: dynamic module does not define module export function (PyInit_my_bindings_module)"}]}