pythoncapi_compat.h API

The pythoncapi_compat.h header file provides implementations of recent functions for old Python versions.

Supported Python versions:

  • Python 3.5 - 3.12

  • PyPy 2.7

  • PyPy 3.6 - 3.9

Python 2.7 and Python 3.4 are no longer officially supported since GitHub Actions doesn’t support them anymore: only best effort support is provided.

C++03 and C++11 are supported on Python 3.6 and newer.

A C99 subset is required, like static inline functions: see PEP 7. ISO C90 is partially supported for Python 2.7.

Some functions related to frame objects and PyThreadState are not available on PyPy.

Latest version of the header file: pythoncapi_compat.h.

Python 3.13

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)

See PyDict_GetItemRef() documentation.

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)

See PyDict_GetItemStringRef() documentation.

PyObject *PyImport_AddModuleRef(const char *name)

See PyImport_AddModuleRef() documentation.

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result)

See PyObject_GetOptionalAttr() documentation.

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result)

See PyObject_GetOptionalAttrString() documentation.

int PyObject_HasAttrWithError(PyObject *obj, PyObject *attr_name)

See PyObject_HasAttrWithError() documentation.

int PyObject_HasAttrStringWithError(PyObject *obj, const char *attr_name)

See PyObject_HasAttrStringWithError() documentation.

int PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **result)

See PyMapping_GetOptionalItem() documentation.

int PyMapping_GetOptionalItemString(PyObject *obj, const char *key, PyObject **result)

See PyMapping_GetOptionalItemString() documentation.

int PyMapping_HasKeyWithError(PyObject *obj, PyObject *key)

See PyMapping_HasKeyWithError() documentation.

int PyMapping_HasKeyStringWithError(PyObject *obj, const char *key)

See PyMapping_HasKeyStringWithError() documentation.

int PyModule_Add(PyObject *module, const char *name, PyObject *value)

See PyModule_Add() documentation.

int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)

See PyWeakref_GetRef() documentation.

int Py_IsFinalizing()

Return non-zero if the Python interpreter is shutting down, return 0 otherwise.

Availability: Python 3.3 and newer, PyPy 7.3 and newer.

See Py_IsFinalizing() documentation.

int PyDict_ContainsString(PyObject *p, const char *key)

See PyDict_ContainsString() documentation.

int PyLong_AsInt(PyObject *obj)

See PyLong_AsInt() documentation.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)

See PyObject_VisitManagedDict() documentation.

void PyObject_ClearManagedDict(PyObject *obj)

See PyObject_ClearManagedDict() documentation.

PyThreadState *PyThreadState_GetUnchecked(void)

See PyThreadState_GetUnchecked() documentation.

Available on Python 3.5.2 and newer.

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *str)

See PyUnicode_EqualToUTF8() documentation.

int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *str, Py_ssize_t size)

See PyUnicode_EqualToUTF8AndSize() documentation.

int PyList_Extend(PyObject *list, PyObject *iterable)

See PyList_Extend() documentation.

int PyList_Clear(PyObject *list)

See PyList_Clear() documentation.

int PyDict_Pop(PyObject *dict, PyObject *key, PyObject **result)

See PyDict_Pop() documentation.

int PyDict_PopString(PyObject *dict, const char *key, PyObject **result)

See PyDict_PopString() documentation.

Python 3.12

PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)

See PyFrame_GetVar() documentation.

Not available on PyPy.

PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)

See PyFrame_GetVarString() documentation.

Not available on PyPy.

Python 3.11

PyObject *PyCode_GetCellvars(PyCodeObject *code)

See PyCode_GetCellvars() documentation.

Not available on PyPy.

PyObject *PyCode_GetCode(PyCodeObject *code)

See PyCode_GetCode() documentation.

Not available on PyPy.

PyObject *PyCode_GetFreevars(PyCodeObject *code)

See PyCode_GetFreevars() documentation.

Not available on PyPy.

PyObject *PyCode_GetVarnames(PyCodeObject *code)

See PyCode_GetVarnames() documentation.

Not available on PyPy.

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)

See PyFrame_GetBuiltins() documentation.

Not available on PyPy.

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)

See PyFrame_GetGlobals() documentation.

Not available on PyPy.

int PyFrame_GetLasti(PyFrameObject *frame)

See PyFrame_GetLasti() documentation.

Not available on PyPy.

PyObject *PyFrame_GetLocals(PyFrameObject *frame)

See PyFrame_GetLocals() documentation.

Not available on PyPy.

void PyThreadState_EnterTracing(PyThreadState *tstate)

See PyThreadState_EnterTracing() documentation.

Not available on PyPy.

void PyThreadState_LeaveTracing(PyThreadState *tstate)

See PyThreadState_LeaveTracing() documentation.

Not available on PyPy

int PyFloat_Pack2(double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary16 half-precision format.

Availability: Python 3.6 and newer. Not available on PyPy

int PyFloat_Pack4(double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary32 single precision format.

Not available on PyPy

int PyFloat_Pack8(double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary64 double precision format.

Not available on PyPy

double PyFloat_Unpack2(const unsigned char *p, int le)

Unpack the IEEE 754 binary16 half-precision format as a C double.

Availability: Python 3.6 and newer. Not available on PyPy

double PyFloat_Unpack4(const unsigned char *p, int le)

Unpack the IEEE 754 binary32 single precision format as a C double.

Not available on PyPy

double PyFloat_Unpack8(const unsigned char *p, int le)

Unpack the IEEE 754 binary64 double precision format as a C double.

Not available on PyPy

Python 3.10

PyObject *Py_NewRef(PyObject *obj)

See Py_NewRef() documentation.

PyObject *Py_XNewRef(PyObject *obj)

See Py_XNewRef() documentation.

int Py_Is(PyObject *x, PyObject *y)

See Py_Is() documentation.

int Py_IsNone(PyObject *x)

See Py_IsNone() documentation.

int Py_IsTrue(PyObject *x)

See Py_IsTrue() documentation.

int Py_IsFalse(PyObject *x)

See Py_IsFalse() documentation.

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)

See PyModule_AddObjectRef() documentation.

Python 3.9

PyObject

void Py_SET_REFCNT(PyObject *ob, Py_ssize_t refcnt)

See Py_SET_REFCNT() documentation.

void Py_SET_TYPE(PyObject *ob, PyTypeObject *type)

See Py_SET_TYPE() documentation.

void Py_SET_SIZE(PyVarObject *ob, Py_ssize_t size)

See Py_SET_SIZE() documentation.

int Py_IS_TYPE(const PyObject *ob, const PyTypeObject *type)

See Py_IS_TYPE() documentation.

PyObject *PyObject_CallNoArgs(PyObject *func)

See PyObject_CallNoArgs() documentation.

PyObject *PyObject_CallOneArg(PyObject *func, PyObject *arg)

See PyObject_CallOneArg() documentation.

PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

See PyObject_Vectorcall() documentation.

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

See PyVectorcall_NARGS() documentation.

PY_VECTORCALL_ARGUMENTS_OFFSET

See PY_VECTORCALL_ARGUMENTS_OFFSET documentation.

PyFrameObject

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)

See PyFrame_GetCode() documentation.

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)

See PyFrame_GetBack() documentation.

Not available on PyPy

PyThreadState

PyFrameObject *PyThreadState_GetFrame(PyThreadState *tstate)

See PyThreadState_GetFrame() documentation.

Not available on PyPy

PyInterpreterState *PyThreadState_GetInterpreter(PyThreadState *tstate)

See PyThreadState_GetInterpreter() documentation.

uint64_t PyThreadState_GetID(PyThreadState *tstate)

See PyThreadState_GetID() documentation.

Availability: Python 3.7. Not available on PyPy.

PyInterpreterState

PyInterpreterState *PyInterpreterState_Get(void)

See PyInterpreterState_Get() documentation.

GC protocol

int PyObject_GC_IsTracked(PyObject *obj)

See PyObject_GC_IsTracked() documentation.

Not available on PyPy.

int PyObject_GC_IsFinalized(PyObject *obj)

See PyObject_GC_IsFinalized() documentation.

Availability: Python 3.4. Not available on PyPy.

Module helper

int PyModule_AddType(PyObject *module, PyTypeObject *type)

See PyModule_AddType() documentation.

Python 3.5.2

Py_SETREF(op, op2)
Py_XSETREF(op, op2)

Python 3.4

Py_UNUSED(name)

See Py_UNUSED() documentation.

Borrow variant

To ease migration of C extensions to the new C API, a variant is provided to return borrowed references rather than strong references.

These functions are only available in pythoncapi_compat.h and are not part of the Python C API.

PyObject *_Py_StealRef(PyObject *ob)

Similar to Py_DECREF(ob); return ob;.

PyObject *_Py_XStealRef(PyObject *ob)

Similar to Py_XDECREF(ob); return ob;.

PyFrameObject *_PyThreadState_GetFrameBorrow(PyThreadState *tstate)

PyThreadState_GetFrame() variant. Not available on PyPy.

PyCodeObject *_PyFrame_GetCodeBorrow(PyFrameObject *frame)

PyFrame_GetCode() variant.

PyFrameObject *_PyFrame_GetBackBorrow(PyFrameObject *frame)

PyFrame_GetBack() variant Not available on PyPy.

For example, tstate->frame can be replaced with _PyThreadState_GetFrameBorrow(tstate) to avoid accessing directly PyThreadState.frame member.