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.13
PyPy 2.7 and PyPy 3.6 - 3.10

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 C11 subset (without optional features) 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.

Py_hash_t Py_HashPointer(const void *ptr)¶: See Py_HashPointer() documentation.

type PyTime_t¶: A timestamp or duration in nanoseconds, represented as a signed 64-bit integer.

PyTime_t PyTime_MIN¶: Minimum value of PyTime_t.

PyTime_t PyTime_MAX¶: Maximum value of PyTime_t.

double PyTime_AsSecondsDouble(PyTime_t t)¶: See PyTime_AsSecondsDouble() documentation.

int PyTime_Monotonic(PyTime_t *result)¶: See PyTime_Monotonic() documentation.

int PyTime_Time(PyTime_t *result)¶: See PyTime_Time() documentation.

int PyTime_PerfCounter(PyTime_t *result)¶: See PyTime_PerfCounter() documentation.

PyObject *PyList_GetItemRef(PyObject *op, Py_ssize_t index)¶: See PyList_GetItemRef() documentation.

int PyDict_SetDefaultRef(PyObject *d, PyObject *key, PyObject *default_value, PyObject **result)¶: See PyDict_SetDefaultRef() documentation.

Not supported:

PyErr_FormatUnraisable().
PyLong_AsNativeBytes()
PyLong_FromNativeBytes()
PyLong_FromUnsignedNativeBytes()
PyObject_GenericHash().
PySys_Audit().
PySys_AuditTuple().
PyType_GetFullyQualifiedName()
PyType_GetModuleName()

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.

PyObject *Py_GetConstant(unsigned int constant_id)¶: See Py_GetConstant() documentation.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶: See Py_GetConstantBorrowed() documentation.

Not supported:

PyDict_AddWatcher(), PyDict_Watch().
PyCode_AddWatcher(), PyCode_ClearWatcher().
PyErr_GetRaisedException(), PyErr_SetRaisedException().
_PyErr_ChainExceptions1().
PyErr_DisplayException().
_Py_IsImmortal().
Py_NewInterpreterFromConfig().
PyException_GetArgs(), PyException_SetArgs().
PyEval_SetProfileAllThreads(), PyEval_SetTraceAllThreads().
PyFunction_SetVectorcall().
PyType_FromMetaclass(): implementation too big to be backported.
PyVectorcall_Call().

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

Not supported:

PyType_GetModuleByDef().
PyType_GetName().
PyType_GetQualName().
Py_Version constant.
PyErr_GetHandledException(), PyErr_SetHandledException().
PyFrame_GetGenerator().

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.

Not supported:

PyCodec_Unregister().
PyDateTime_DATE_GET_TZINFO(), PyDateTime_TIME_GET_TZINFO().
PyErr_SetInterruptEx().
PyGC_Enable(), PyGC_Disable() and PyGC_IsEnabled().
PyIter_Send().
PySet_CheckExact().
Py_TPFLAGS_DISALLOW_INSTANTIATION constant.
Py_TPFLAGS_IMMUTABLETYPE constant.

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.

Not supported:

PyVectorcall_CallMethod().
PyType_FromModuleAndSpec()

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.8¶

Not supported:

PyCode_NewWithPosOnlyArgs().

Python 3.7¶

Not supported:

PyImport_GetModule().
PyInterpreterState_GetID().
PySlice_Unpack(), PySlice_AdjustIndices().
PyTimeZone_FromOffset(), PyTimeZone_FromOffsetAndName().
Py_RETURN_RICHCOMPARE().
Py_UNREACHABLE macro.

Python 3.6¶

Not supported:

PyErr_ResourceWarning().
PyErr_SetImportErrorSubclass().
PyOS_FSPath().
Py_FinalizeEx().

Python 3.5.2¶

Py_SETREF(op, op2)¶

Py_XSETREF(op, op2)¶

Not supported:

PyCodec_NameReplaceErrors().
PyErr_FormatV().
PyExc_RecursionError.
PyModule_FromDefAndSpec(), PyModule_FromDefAndSpec2(), and PyModule_ExecDef().
PyNumber_MatrixMultiply() and PyNumber_InPlaceMatrixMultiply().

Python 3.4¶

Py_UNUSED(name)¶: See Py_UNUSED() documentation.

Python 3.2¶

Not supported:

Py_VA_COPY.
PySys_SetArgvEx().
PyLong_AsLongLongAndOverflow().
PyErr_NewExceptionWithDoc().

Python 3.1¶

Not supported:

PyOS_string_to_double().
PyCapsule API.

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.

pythoncapi_compat.h API¶

Python 3.13¶

Python 3.12¶

Python 3.11¶

Python 3.10¶

Python 3.9¶

PyObject¶

PyFrameObject¶

PyThreadState¶

PyInterpreterState¶

GC protocol¶

Module helper¶

Python 3.8¶

Python 3.7¶

Python 3.6¶

Python 3.5.2¶

Python 3.4¶

Python 3.2¶

Python 3.1¶

Borrow variant¶

Table of Contents

Previous topic

Next topic

This Page