Registry / devops / cppy
library1.3.1pypypi✓ verified 23d ago

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 cppy
INSTALL
IMPORT
SIG · CPPY
C
cppy
devopspythonv1.3.1
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.3.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
glibc
py 3.10
1/2 runs
1/2 runs
py 3.11
1/2 runs
1/2 runs
py 3.12
1/2 runs
1/2 runs
py 3.13
1/2 runs
1/2 runs
py 3.9
1/2 runs
1/2 runs
Code
Verified usage

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

cppy/cppy.h
#include <cppy/cppy.h>
This is a C++ header inclusion, not a Python import. Cppy provides its functionalities within the 'cppy' C++ namespace.
CppyBuildExt
from cppy import CppyBuildExt
This Python import is used in a 'setup.py' script for building C++ extensions with setuptools, ensuring C++11 and access to cppy headers.

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`.

import os from setuptools import setup, Extension from setuptools.command.build_ext import build_ext # A minimal C++ source file that includes cppy # In a real project, this would be in a separate .cpp file cpp_source = ''' #include <Python.h> #include <cppy/cppy.h> static PyObject* greet_method(PyObject* self, PyObject* args) { const char* name; if (!PyArg_ParseTuple(args, "s", &name)) { return NULL; } std::string greeting = "Hello, " + std::string(name) + "!"; cppy::ptr result_ptr(PyUnicode_FromString(greeting.c_str())); return result_ptr.release(); // release ownership to Python } static PyMethodDef methods[] = { {"greet", greet_method, METH_VARARGS, "Greet a person."}, {NULL, NULL, 0, NULL} }; static struct PyModuleDef mymodule = { PyModuleDef_HEAD_INIT, "_my_extension", // Name of the module NULL, // Module documentation -1, // Size of per-interpreter state of the module methods }; PyMODINIT_FUNC PyInit__my_extension(void) { return PyModule_Create(&mymodule); } ''' # Write the C++ code to a temporary file for demonstration with open('my_extension_module.cpp', 'w') as f: f.write(cpp_source) class CustomBuildExt(build_ext): def build_extension(self, ext): # Example of setting C++ standard if not using CppyBuildExt directly # For cppy, C++11 is typically required. if self.compiler.compiler_type == 'msvc': ext.extra_compile_args = ['/std:c++11'] else: ext.extra_compile_args = ['-std=c++11'] super().build_extension(ext) setup( name='my-cpp-extension', version='0.1.0', description='A simple C++ extension using cppy', ext_modules=[ Extension( '_my_extension', sources=['my_extension_module.cpp'], include_dirs=[os.path.join(os.environ.get('VIRTUAL_ENV', '/usr/local'), 'include')], # Adjust if cppy headers not found language='c++' ) ], # For real projects, you might use CppyBuildExt directly: # cmdclass={'build_ext': CppyBuildExt}, # Or ensure cppy is in build-system.requires in pyproject.toml # and then 'from cppy import CppyBuildExt' in setup.py cmdclass={'build_ext': CustomBuildExt}, setup_requires=['cppy'], # Ensure cppy is available during setup install_requires=[] ) # To demonstrate usage after hypothetical build and installation: # import _my_extension # print(_my_extension.greet("World"))
Debug
Known issues
gotchaCppy is a C++ header library, not a Python module for direct runtime import. Its primary use is during the compilation of Python C++ extension modules. The Python 'cppy' package provides build-time integration components like `CppyBuildExt` for `setup.py`.
fix
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`.
affects: All
breakingCppy requires C++11 or a later standard for compilation. Older C++ compilers or build configurations not explicitly setting C++11 (or newer) will fail to compile extensions using Cppy.
fix
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.
affects: All
gotchaProperly managing reference counts in Python C extensions is a common source of bugs. Cppy's `cppy::ptr` smart pointer is designed to alleviate this by automatically handling `Py_INCREF` and `Py_DECREF`.
fix
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()`.
affects: All
gotchaOn Windows, when compiling, you might encounter issues related to FH4 Exception Handling, potentially requiring `VCRUNTIME140_1.dll`. This can be disabled if not needed.
fix
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`).
affects: All
gotchaWhen using `setuptools` with a PEP 517 compatible build system (i.e., `pyproject.toml`), `cppy` must be listed as a build-time requirement to be available during the `setup.py` execution.
fix
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"]`).
affects: All
Errors
Common errors & fixes
fatal error: Python.h: No such file or directory
The C++ compiler cannot find the Python development header files, which are essential for building Python extension modules.
fix
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.
TypeError: argument of type 'X' is not compatible with parameter of type 'Y'
A Python object was passed to a C++ function (wrapped by cppy) that expected a different Python type or a convertible type, leading to a type mismatch during argument conversion.
fix
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.
undefined reference to 'Py...' (e.g., PyObject_Call, Py_BuildValue)
The linker cannot find the implementation of Python C API functions because the Python library was not correctly linked during the compilation of your C++ extension module.
fix
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.
Upgrade
Version history
1.3.1latest on PyPI · released Feb 11, 2025
Audit
Dependencies
setuptoolsrequiredRequired as a build dependency for Python extensions using cppy.
wheelrequiredCommonly used alongside setuptools for building Python wheels.
Agent activity
18 hits · last 30 days
node
16
Resources
cppy — pip install cppy · libregistry