Skip to main content

Include/pycapsule.h

Source:

cpython 3.14 @ ab2d84fe1023/Include/pycapsule.h

PyCapsule is a Python object that wraps an opaque C pointer. It is the standard mechanism for C extension modules to pass C-level pointers (struct pointers, function pointers, resources) to other C extensions or to store them in Python data structures.

Map​

LinesSymbolRole
1-20PyCapsule_TypeType declaration
21-55PyCapsule_New, PyCapsule_GetPointer, PyCapsule_GetName, PyCapsule_SetDestructor, PyCapsule_ImportPublic API

Reading​

PyCapsule_New​

// CPython: Include/pycapsule.h:30 PyCapsule_New
PyAPI_FUNC(PyObject *) PyCapsule_New(
    void *pointer,
    const char *name,
    PyCapsule_Destructor destructor);

Creates a capsule containing pointer. The name is a string identifier (usually "module.symbol") used to verify the capsule type on extraction. destructor is called when the capsule is garbage collected.

PyCapsule_GetPointer​

// CPython: Include/pycapsule.h:35 PyCapsule_GetPointer
PyAPI_FUNC(void *) PyCapsule_GetPointer(PyObject *capsule, const char *name);

Extracts the pointer. If name does not match the capsule's name, raises PyCapsuleError and returns NULL. This prevents accidentally passing a capsule from one module to another that expects a different type.

PyCapsule_Import​

// CPython: Include/pycapsule.h:55 PyCapsule_Import
PyAPI_FUNC(void *) PyCapsule_Import(
    const char *name,
    int no_block);

Looks up a capsule by dotted name: imports the module name.split('.')[0], then retrieves sys.modules[module].attribute. Used by NumPy and other C extensions to share C-level APIs via the "capsule import" pattern.

Use case: sharing C APIs​

NumPy exports its C API as a capsule at numpy.core.multiarray._ARRAY_API. Other C extensions import that capsule to call NumPy C functions directly without going through PyObject_Call.

gopy notes​

PyCapsule is not yet implemented in gopy. It is needed for C extension interoperability (cgo-based extensions). A gopy CapsuleObject would store a unsafe.Pointer and a name string, with a Go finalizer as the destructor callback.