Cppy (Python C++ Extension Headers)

Warnings

• gotcha Cppy 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`.
• breaking Cppy 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.
• gotcha Properly 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()`.
• gotcha On 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`).
• gotcha When 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"]`).

Install

• pip install cppy Install stable version
• pip install git+https://github.com/nucleic/cppy Install development version

Imports

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

Quickstart

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"))