Cppy is a small C++ header library designed to simplify the creation of Python extension modules. Its core feature is a `PyObject` smart pointer, which automates Python's reference counting mechanism and provides convenient methods for common object operations. The current version is 1.3.1. As a C++ header library, its release cadence is typically driven by CPython API changes or new convenience features rather than a fixed schedule.
pip install cppyVerified import paths — ran on the pinned version, not inferred.
To use Cppy, you write C++ code for your Python extension module and include the `cppy/cppy.h` header. This example shows a `setup.py` that would build a simple C++ extension. Cppy handles Python object reference counting through its `cppy::ptr` smart pointer. For a more direct integration with `setuptools`, you can import `CppyBuildExt` from the `cppy` package in your `setup.py` to automatically enforce C++11 and include the necessary headers. Alternatively, specify `cppy` as a build requirement in `pyproject.toml`.
Understand that `pip install cppy` makes the C++ headers available for your C++ compiler. Python-side, you might import `CppyBuildExt` in your `setup.py` or declare `cppy` as a build-system requirement in `pyproject.toml`.
Ensure your C++ compiler is configured to use C++11 (e.g., `-std=c++11` for GCC/Clang or `/std:c++11` for MSVC). `CppyBuildExt` aims to enforce this automatically when used.
Always wrap raw `PyObject*` pointers obtained from Python API calls (that give a new reference) or those you intend to return to Python (after acquiring a new reference) in `cppy::ptr` to ensure correct reference counting, especially when returning an object to Python using `cppy::ptr::release()`.
Set the environment variable `CPPY_DISABLE_FH4=1` during the build process to disable FH4 Exception Handling and avoid this dependency if it's causing issues. This should be done before running your build command (e.g., `set CPPY_DISABLE_FH4=1 && python setup.py install`).
Include `cppy>=1.2` (or your desired version) in the `[build-system] requires` section of your `pyproject.toml` file (e.g., `requires = ["setuptools>=42", "wheel", "cppy>=1.2"]`).
Install the Python development headers for your specific Python version. On Debian/Ubuntu, use `sudo apt-get install python3-dev` (or `python-dev` for Python 2). On Fedora/RHEL, use `sudo dnf install python3-devel` (or `python-devel`). Ensure your build system's include paths are correctly configured to point to these headers.
Ensure the Python arguments passed to your cppy-wrapped C++ functions match the expected types in the C++ signature, or that implicit conversions are possible. Review the C++ function signature and the Python call site.
Ensure your build system (e.g., setup.py with setuptools, CMake) correctly links against the Python library. This typically involves adding `-lpythonX.Y` (where X.Y is your Python version) to the linker flags and ensuring the linker search paths (`-L`) include the directory where `libpythonX.Y.so` (or `.dylib`, `.lib`) is located.