pythoncapi_compat.h API¶

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

Supported Python versions:

Python 3.6 - 3.14
PyPy 2.7 and PyPy 3.6 - 3.10

Python 2.7 and Python 3.5 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.15¶

PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)¶

void *PyBytesWriter_GetData(PyBytesWriter *writer)¶

Py_ssize_t PyBytesWriter_GetSize(PyBytesWriter *writer)¶

PyObject *PyBytesWriter_FinishWithSize(PyBytesWriter *writer, Py_ssize_t size)¶

PyObject *PyBytesWriter_Finish(PyBytesWriter *writer)¶

PyObject *PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)¶

void PyBytesWriter_Discard(PyBytesWriter *writer)¶

int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size)¶

int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t size)¶

void *PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)¶

int PyBytesWriter_WriteBytes(PyBytesWriter *writer, const void *bytes, Py_ssize_t size)¶

int PyBytesWriter_Format(PyBytesWriter *writer, const char *format, ...)¶: See PyBytesWriter documentation.

PyObject *PySys_GetAttr(const char *name)¶: See PySys_GetAttr() documentation.

PyObject *PySys_GetAttrString(const char *name)¶: See PySys_GetAttrString() documentation.

PyObject *PySys_GetOptionalAttr(const char *name)¶: See PySys_GetOptionalAttr() documentation.

PyObject *PySys_GetOptionalAttrString(const char *name)¶: See PySys_GetOptionalAttrString() documentation.

PyObject *PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)¶: See PyTuple_FromArray() documentation.

Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *op)¶

See PyUnstable_Unicode_GET_CACHED_HASH() documentation.

On PyPy, always returns -1.

Python 3.14¶

struct PyLongLayout¶: See PyLongLayout documentation.

const PyLongLayout *PyLong_GetNativeLayout(void)¶: See PyLong_GetNativeLayout() documentation.

struct PyLongExport¶: See PyLongExport documentation.

int PyLong_Export(PyObject *obj, PyLongExport *export_long)¶: See PyLong_Export() documentation.

void PyLong_FreeExport(PyLongExport *export_long)¶: See PyLong_FreeExport() documentation.

struct PyLongWriter¶: See PyLongWriter documentation.

PyLongWriter *PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)¶: See PyLongWriter_Create() documentation.

PyObject *PyLongWriter_Finish(PyLongWriter *writer)¶: See PyLongWriter_Finish() documentation.

void PyLongWriter_Discard(PyLongWriter *writer)¶: See PyLongWriter_Discard() documentation.

int PyLong_IsPositive(PyObject *obj)¶: See PyLong_IsPositive() documentation.

int PyLong_IsNegative(PyObject *obj)¶: See PyLong_IsNegative() documentation.

int PyLong_IsZero(PyObject *obj)¶: See PyLong_IsZero() documentation.

int PyLong_GetSign(PyObject *obj, int *sign)¶: See PyLong_GetSign() documentation.

PyObject *PyIter_NextItem(PyObject *sep, PyObject *iterable)¶: See PyIter_NextItem() documentation.

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)¶: See PyBytes_Join() documentation.

Py_hash_t Py_HashBuffer(const void *ptr, Py_ssize_t len)¶: See Py_HashBuffer() documentation.

int PyUnicode_Equal(PyObject *str1, PyObject *str2)¶: See PyUnicode_Equal() documentation.

PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)¶: See PyUnicodeWriter_Create() documentation.

PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)¶: See PyUnicodeWriter_Finish() documentation.

void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)¶: See PyUnicodeWriter_Discard() documentation.

int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)¶: See PyUnicodeWriter_WriteChar() documentation.

int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶: See PyUnicodeWriter_WriteUTF8() documentation.

int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶: See PyUnicodeWriter_WriteASCII() documentation.

int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)¶: See PyUnicodeWriter_WriteWideChar() documentation.

int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)¶: See PyUnicodeWriter_WriteStr() documentation.

int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)¶: See PyUnicodeWriter_WriteRepr() documentation.

int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)¶: See PyUnicodeWriter_WriteSubstring() documentation.

int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)¶: See PyUnicodeWriter_Format() documentation.

int PyLong_AsInt32(PyObject *obj, int32_t *pvalue)¶: See PyLong_AsInt32() documentation.

int PyLong_AsInt64(PyObject *obj, int64_t *pvalue)¶: See PyLong_AsInt64() documentation.

int PyLong_AsUInt32(PyObject *obj, uint32_t *pvalue)¶: See PyLong_AsUInt32() documentation.

int PyLong_AsUInt64(PyObject *obj, uint64_t *pvalue)¶: See PyLong_AsUInt64() documentation.

PyObject *PyLong_FromInt32(int32_t value)¶: See PyLong_FromInt32() documentation.

PyObject *PyLong_FromInt64(int64_t value)¶: See PyLong_FromInt64() documentation.

PyObject *PyLong_FromUInt32(uint32_t value)¶: See PyLong_FromUInt32() documentation.

PyObject *PyLong_FromUInt64(uint64_t value)¶: See PyLong_FromUInt64() documentation.

FILE *Py_fopen(PyObject *path, const char *mode)¶: See Py_fopen() documentation.

int Py_fclose(FILE *file)¶: See Py_fclose() documentation.

PyObject *PyConfig_Get(const char *name)¶: See PyConfig_Get() documentation.

int PyConfig_GetInt(const char *name, int *value)¶: See PyConfig_GetInt() documentation.

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)¶: See PyUnstable_Object_IsUniquelyReferenced() documentation.

Not supported:

PyConfig_Names()
PyConfig_Set()
PyInitConfig_AddModule()
PyInitConfig_Create()
PyInitConfig_Free()
PyInitConfig_FreeStrList()
PyInitConfig_GetError()
PyInitConfig_GetExitCode()
PyInitConfig_GetInt()
PyInitConfig_GetStr()
PyInitConfig_GetStrList()
PyInitConfig_HasOption()
PyInitConfig_SetInt()
PyInitConfig_SetStr()
PyInitConfig_SetStrList()
PyType_GetBaseByToken()
PyUnicodeWriter_DecodeUTF8Stateful()
Py_InitializeFromInitConfig()

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

Python 3.14¶

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