PYTHONCAPI\_COMPAT(1) pythoncapi\_compat PYTHONCAPI\_COMPAT(1) # [NAME](#NAME) pythoncapi\_compat - pythoncapi\_compat The **pythoncapi-compat** project can be used to write a C or C++ extension supporting a wide range of Python versions with a single code base. It is made of the **pythoncapi\_compat.h** header file and the **upgrade\_pythoncapi.py** script. - Homepage: GitHub pythoncapi-compat project <https://github.com/python/pythoncapi-compat>. - Documentation <https://pythoncapi-compat.readthedocs.io/en/latest/> Documentation: # [UPGRADE\_PYTHONCAPI.PY SCRIPT](#UPGRADE_PYTHONCAPI.PY_SCRIPT) **upgrade\_pythoncapi.py** requires Python 3.6 or newer. ## [Usage](#Usage) Run the with no arguments to display command line options and list available operations: ``` python3 upgrade_pythoncapi.py ``` ## [Select files and directories](#Select_files_and_directories) To upgrade **module.c** file, type: ``` python3 upgrade_pythoncapi.py module.c ``` To upgrade all C and C++ files (**.c**, **.h**, **.cc**, **.cpp**, **.cxx** and **.hpp** files) in the **directory/** directory, type: ``` python3 upgrade_pythoncapi.py directory/ ``` Multiple filenames an directories can be specified on the command line. Files are modified in-place! If a file is modified, a copy of the original file is created with the **.old** suffix. ## [Select operations](#Select_operations) To only replace **op->ob\_type** with **Py\_TYPE(op)**, select the **Py\_TYPE** operation with: ``` python3 upgrade_pythoncapi.py -o Py_TYPE module.c ``` Or the opposite, to apply all operations but leave **op->ob\_type** unchanged, deselect the **Py\_TYPE** operation with: ``` python3 upgrade_pythoncapi.py -o all,-Py_TYPE module.c ``` ## [Download pythoncapi\_compat.h](#Download_pythoncapi_compat.h) Most **upgrade\_pythoncapi.py** operations add **#include** **"pythoncapi\_compat.h"**. You may have to download the **pythoncapi\_compat.h** header file to your project. It can be downloaded with: ``` python3 upgrade_pythoncapi.py --download PATH ``` ## [Upgrade Operations](#Upgrade_Operations) **upgrade\_pythoncapi.py** implements the following operations: ## [Py\_TYPE](#Py_TYPE) • Replace **op->ob\_type** with **Py\_TYPE(op)**. ## [Py\_SIZE](#Py_SIZE) • Replace **op->ob\_size** with **Py\_SIZE(op)**. ## [Py\_REFCNT](#Py_REFCNT) • Replace **op->ob\_refcnt** with **Py\_REFCNT(op)**. ## [Py\_SET\_TYPE](#Py_SET_TYPE) - Replace **obj->ob\_type = type;** with **Py\_SET\_TYPE(obj, type);**. - Replace **Py\_TYPE(obj) = type;** with **Py\_SET\_TYPE(obj, type);**. ## [Py\_SET\_SIZE](#Py_SET_SIZE) - Replace **obj->ob\_size = size;** with **Py\_SET\_SIZE(obj, size);**. - Replace **Py\_SIZE(obj) = size;** with **Py\_SET\_SIZE(obj, size);**. ## [Py\_SET\_REFCNT](#Py_SET_REFCNT) - Replace **obj->ob\_refcnt = refcnt;** with **Py\_SET\_REFCNT(obj, refcnt);**. - Replace **Py\_REFCNT(obj) = refcnt;** with **Py\_SET\_REFCNT(obj, refcnt);**. ## [Py\_Is](#Py_Is) - Replace **x == Py\_None** with **Py\_IsNone(x)**. - Replace **x == Py\_True** with **Py\_IsTrue(x)**. - Replace **x == Py\_False** with **Py\_IsFalse(x)**. - Replace **x != Py\_None** with **!Py\_IsNone(x)**. - Replace **x != Py\_True** with **!Py\_IsTrue(x)**. - Replace **x != Py\_False** with **!Py\_IsFalse(x)**. ## [PyObject\_NEW](#PyObject_NEW) - Replace **PyObject\_NEW(...)** with **PyObject\_New(...)**. - Replace **PyObject\_NEW\_VAR(...)** with **PyObject\_NewVar(...)**. ## [PyMem\_MALLOC](#PyMem_MALLOC) - Replace [**PyMem\_MALLOC(n)**](/man/enterprise-packages/pythoncapi-compat/PyMem_MALLOC.n) with [**PyMem\_Malloc(n)**](/man/enterprise-packages/pythoncapi-compat/PyMem_Malloc.n). - Replace **PyMem\_REALLOC(ptr, n)** with **PyMem\_Realloc(ptr, n)**. - Replace **PyMem\_FREE(ptr)**, **PyMem\_DEL(ptr)** and **PyMem\_Del(ptr)** . with [**PyMem\_Free(n)**](/man/enterprise-packages/pythoncapi-compat/PyMem_Free.n). ## [PyObject\_MALLOC](#PyObject_MALLOC) - Replace [**PyObject\_MALLOC(n)**](/man/enterprise-packages/pythoncapi-compat/PyObject_MALLOC.n) with [**PyObject\_Malloc(n)**](/man/enterprise-packages/pythoncapi-compat/PyObject_Malloc.n). - Replace **PyObject\_REALLOC(ptr, n)** with **PyObject\_Realloc(ptr, n)**. - Replace **PyObject\_FREE(ptr)**, **PyObject\_DEL(ptr)** and **PyObject\_Del(ptr)** . with [**PyObject\_Free(n)**](/man/enterprise-packages/pythoncapi-compat/PyObject_Free.n). ## [PyFrame\_GetBack](#PyFrame_GetBack) • Replace **frame->f\_back** with **\_PyFrame\_GetBackBorrow(frame)**. ## [PyFrame\_GetCode](#PyFrame_GetCode) • Replace **frame->f\_code** with **\_PyFrame\_GetCodeBorrow(frame)**. ## [PyThreadState\_GetInterpreter](#PyThreadState_GetInterpreter) • Replace **tstate->interp** with **PyThreadState\_GetInterpreter(tstate)**. ## [PyThreadState\_GetFrame](#PyThreadState_GetFrame) • Replace **tstate->frame** with **\_PyThreadState\_GetFrameBorrow(tstate)**. ## [Experimental operations](#Experimental_operations) The following operations are experimental (ex: can introduce compiler warnings) and so not included in the **all** group, they have to be selected explicitly. Example: **-o all,Py\_SETREF**. Experimental operations: • **Py\_NewRef**: - Replace **Py\_INCREF(res); return res;** with **return Py\_NewRef(res);** - Replace **x = y; Py\_INCREF(x);** with **x = Py\_NewRef(y);** - Replace **x = y; Py\_INCREF(y);** with **x = Py\_NewRef(y);** - Replace **Py\_INCREF(y); x = y;** with **x = Py\_NewRef(y);** • **Py\_CLEAR**: • Replace **Py\_XDECREF(var); var = NULL;** with **Py\_CLEAR(var);** • **Py\_SETREF**: - Replace **Py\_DECREF(x); x = y;** with **Py\_SETREF(x, y);** - Replace **Py\_XDECREF(x); x = y;** with **Py\_XSETREF(x, y);** # [PYTHONCAPI\_COMPAT.H API](#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.15 - PyPy 3.6 - 3.12 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 <https://www.python.org/dev/peps/pep-0007/>. Some functions related to frame objects and **PyThreadState** are not available on PyPy. Latest version of the header file: pythoncapi\_compat.h <https://raw.githubusercontent.com/python/pythoncapi-compat/main/pythoncapi\_compat.h>. ## [Python 3.15](#Python_3.15) [**PyBytesWriter \*PyBytesWriter\_Create(Py\_ssize\_t size)**](#PyBytesWriter) [**void \*PyBytesWriter\_GetData(PyBytesWriter \*writer)**](#void) [**Py\_ssize\_t PyBytesWriter\_GetSize(PyBytesWriter \*writer)**](#Py_ssize_t) **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)**](#void~2) [**int PyBytesWriter\_Resize(PyBytesWriter \*writer, Py\_ssize\_t size)**](#int) [**int PyBytesWriter\_Grow(PyBytesWriter \*writer, Py\_ssize\_t size)**](#int~2) [**void \*PyBytesWriter\_GrowAndUpdatePointer(PyBytesWriter \*writer, Py\_ssize\_t size, void \*buf)**](#void~3) [**int PyBytesWriter\_WriteBytes(PyBytesWriter \*writer, const void \*bytes, Py\_ssize\_t size)**](#int~3) [**int PyBytesWriter\_Format(PyBytesWriter \*writer, const char \*format, ...)**](#int~4) See PyBytesWriter documentation <https://docs.python.org/dev/c-api/bytes.html#pybyteswriter>. **PyObject \*PySys\_GetAttr(const char \*name)** See PySys\_GetAttr() documentation <https://docs.python.org/dev/c-api/sys.html#c.PySys\_GetAttr>. **PyObject \*PySys\_GetAttrString(const char \*name)** See PySys\_GetAttrString() documentation <https://docs.python.org/dev/c-api/sys.html#c.PySys\_GetAttrString>. **PyObject \*PySys\_GetOptionalAttr(const char \*name)** See PySys\_GetOptionalAttr() documentation <https://docs.python.org/dev/c-api/sys.html#c.PySys\_GetOptionalAttr>. **PyObject \*PySys\_GetOptionalAttrString(const char \*name)** See PySys\_GetOptionalAttrString() documentation <https://docs.python.org/dev/c-api/sys.html#c.PySys\_GetOptionalAttrString>. **PyObject \*PyTuple\_FromArray(PyObject \*const \*array, Py\_ssize\_t size)** See PyTuple\_FromArray() documentation <https://docs.python.org/dev/c-api/tuple.html#c.PyTuple\_FromArray>. [**Py\_hash\_t PyUnstable\_Unicode\_GET\_CACHED\_HASH(PyObject \*op)**](#Py_hash_t) See PyUnstable\_Unicode\_GET\_CACHED\_HASH() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnstable\_Unicode\_GET\_CACHED\_HASH>. On PyPy, always returns **-1**. [**int PyUnstable\_SetImmortal(PyObject \*op)**](#int~5) See PyUnstable\_SetImmortal() documentation <https://docs.python.org/dev/c-api/object.html#c.PyUnstable\_SetImmortal>. Availability: Python 3.13 and newer, not available on PyPy. ## [Python 3.14](#Python_3.14) [**struct PyLongLayout**](#struct) See PyLongLayout documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongLayout>. [**const PyLongLayout <#c.PyLongLayout> \*PyLong\_GetNativeLayout(void)**](#const) See PyLong\_GetNativeLayout() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_GetNativeLayout>. [**struct PyLongExport**](#struct~2) See PyLongExport documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongExport>. [**int PyLong\_Export(PyObject \*obj, PyLongExport <#c.PyLongExport> \*export\_long)**](#int~6) See PyLong\_Export() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_Export>. [**void PyLong\_FreeExport(PyLongExport <#c.PyLongExport> \*export\_long)**](#void~4) See PyLong\_FreeExport() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_FreeExport>. [**struct PyLongWriter**](#struct~3) See PyLongWriter documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongWriter>. [**PyLongWriter <#c.PyLongWriter> \*PyLongWriter\_Create(int negative, Py\_ssize\_t ndigits, void \*\*digits)**](#PyLongWriter) See PyLongWriter\_Create() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongWriter\_Create>. **PyObject \*PyLongWriter\_Finish(PyLongWriter <#c.PyLongWriter> \*writer)** See PyLongWriter\_Finish() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongWriter\_Finish>. [**void PyLongWriter\_Discard(PyLongWriter <#c.PyLongWriter> \*writer)**](#void~5) See PyLongWriter\_Discard() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLongWriter\_Discard>. [**int PyLong\_IsPositive(PyObject \*obj)**](#int~7) See PyLong\_IsPositive() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_IsPositive>. [**int PyLong\_IsNegative(PyObject \*obj)**](#int~8) See PyLong\_IsNegative() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_IsNegative>. [**int PyLong\_IsZero(PyObject \*obj)**](#int~9) See PyLong\_IsZero() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_IsZero>. [**int PyLong\_GetSign(PyObject \*obj, int \*sign)**](#int~10) See PyLong\_GetSign() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_GetSign>. **PyObject \*PyIter\_NextItem(PyObject \*sep, PyObject \*iterable)** See PyIter\_NextItem() documentation <https://docs.python.org/dev/c-api/iter.html#c.PyIter\_NextItem>. **PyObject \*PyBytes\_Join(PyObject \*sep, PyObject \*iterable)** See PyBytes\_Join() documentation <https://docs.python.org/dev/c-api/bytes.html#c.PyBytes\_Join>. [**Py\_hash\_t Py\_HashBuffer(const void \*ptr, Py\_ssize\_t len)**](#Py_hash_t~2) See Py\_HashBuffer() documentation <https://docs.python.org/dev/c-api/hash.html#c.Py\_HashBuffer>. [**int PyUnicode\_Equal(PyObject \*str1, PyObject \*str2)**](#int~11) See PyUnicode\_Equal() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicode\_Equal>. [**PyUnicodeWriter \*PyUnicodeWriter\_Create(Py\_ssize\_t length)**](#PyUnicodeWriter) See PyUnicodeWriter\_Create() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_Create>. **PyObject \*PyUnicodeWriter\_Finish(PyUnicodeWriter \*writer)** See PyUnicodeWriter\_Finish() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_Finish>. [**void PyUnicodeWriter\_Discard(PyUnicodeWriter \*writer)**](#void~6) See PyUnicodeWriter\_Discard() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_Discard>. [**int PyUnicodeWriter\_WriteChar(PyUnicodeWriter \*writer, Py\_UCS4 ch)**](#int~12) See PyUnicodeWriter\_WriteChar() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_WriteChar>. [**int PyUnicodeWriter\_WriteUTF8(PyUnicodeWriter \*writer, const char \*str, Py\_ssize\_t size)**](#int~13) See PyUnicodeWriter\_WriteUTF8() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_WriteUTF8>. [**int PyUnicodeWriter\_WriteASCII(PyUnicodeWriter \*writer, const char \*str, Py\_ssize\_t size)**](#int~14) See PyUnicodeWriter\_WriteASCII() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_WriteASCII>. [**int PyUnicodeWriter\_WriteWideChar(PyUnicodeWriter \*writer, const wchar\_t \*str, Py\_ssize\_t size)**](#int~15) See PyUnicodeWriter\_WriteWideChar() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_WriteWideChar>. [**int PyUnicodeWriter\_WriteStr(PyUnicodeWriter \*writer, PyObject \*obj)**](#int~16) See PyUnicodeWriter\_WriteStr() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_WriteStr>. [**int PyUnicodeWriter\_WriteRepr(PyUnicodeWriter \*writer, PyObject \*obj)**](#int~17) See PyUnicodeWriter\_WriteRepr() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_WriteRepr>. [**int PyUnicodeWriter\_WriteSubstring(PyUnicodeWriter \*writer, PyObject \*str, Py\_ssize\_t start, Py\_ssize\_t end)**](#int~18) See PyUnicodeWriter\_WriteSubstring() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_WriteSubstring>. [**int PyUnicodeWriter\_Format(PyUnicodeWriter \*writer, const char \*format, ...)**](#int~19) See PyUnicodeWriter\_Format() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicodeWriter\_Format>. [**int PyLong\_AsInt32(PyObject \*obj, int32\_t \*pvalue)**](#int~20) See PyLong\_AsInt32() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_AsInt32>. [**int PyLong\_AsInt64(PyObject \*obj, int64\_t \*pvalue)**](#int~21) See PyLong\_AsInt64() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_AsInt64>. [**int PyLong\_AsUInt32(PyObject \*obj, uint32\_t \*pvalue)**](#int~22) See PyLong\_AsUInt32() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_AsUInt32>. [**int PyLong\_AsUInt64(PyObject \*obj, uint64\_t \*pvalue)**](#int~23) See PyLong\_AsUInt64() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_AsUInt64>. **PyObject \*PyLong\_FromInt32(int32\_t value)** See PyLong\_FromInt32() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_FromInt32>. **PyObject \*PyLong\_FromInt64(int64\_t value)** See PyLong\_FromInt64() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_FromInt64>. **PyObject \*PyLong\_FromUInt32(uint32\_t value)** See PyLong\_FromUInt32() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_FromUInt32>. **PyObject \*PyLong\_FromUInt64(uint64\_t value)** See PyLong\_FromUInt64() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_FromUInt64>. [**FILE \*Py\_fopen(PyObject \*path, const char \*mode)**](#FILE) See Py\_fopen() documentation <https://docs.python.org/dev/c-api/sys.html#c.Py\_fopen>. [**int Py\_fclose(FILE \*file)**](#int~24) See Py\_fclose() documentation <https://docs.python.org/dev/c-api/sys.html#c.Py\_fclose>. **PyObject \*PyConfig\_Get(const char \*name)** See PyConfig\_Get() documentation <https://docs.python.org/dev/c-api/init\_config.html#c.PyConfig\_Get>. [**int PyConfig\_GetInt(const char \*name, int \*value)**](#int~25) See PyConfig\_GetInt() documentation <https://docs.python.org/dev/c-api/init\_config.html#c.PyConfig\_GetInt>. [**int PyUnstable\_Object\_IsUniquelyReferenced(PyObject \*op)**](#int~26) See PyUnstable\_Object\_IsUniquelyReferenced() documentation <https://docs.python.org/dev/c-api/object.html#c.PyUnstable\_Object\_IsUniquelyReferenced>. Not available on PyPy. **Py\_REFCNT()** semantics is different on PyPy. [**int PyUnstable\_TryIncRef(PyObject \*op)**](#int~27) See PyUnstable\_TryIncRef() documentation <https://docs.python.org/dev/c-api/object.html#c.PyUnstable\_TryIncRef>. Not available on PyPy. **Py\_REFCNT()** semantics is different on PyPy. [**void PyUnstable\_EnableTryIncRef(PyObject \*op)**](#void~7) See PyUnstable\_EnableTryIncRef() documentation <https://docs.python.org/dev/c-api/object.html#c.PyUnstable\_EnableTryIncRef>. Not available on PyPy. **Py\_REFCNT()** semantics is different on PyPy. 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()** - **PyUnicodeWriter\_WriteUCS4()** - **Py\_InitializeFromInitConfig()** ## [Python 3.13](#Python_3.13) [**int PyDict\_GetItemRef(PyObject \*p, PyObject \*key, PyObject \*\*result)**](#int~28) See PyDict\_GetItemRef() documentation <https://docs.python.org/dev/c-api/dict.html#c.PyDict\_GetItemRef>. [**int PyDict\_GetItemStringRef(PyObject \*p, const char \*key, PyObject \*\*result)**](#int~29) See PyDict\_GetItemStringRef() documentation <https://docs.python.org/dev/c-api/dict.html#c.PyDict\_GetItemStringRef>. **PyObject \*PyImport\_AddModuleRef(const char \*name)** See PyImport\_AddModuleRef() documentation <https://docs.python.org/dev/c-api/import.html#c.PyImport\_AddModuleRef>. [**int PyObject\_GetOptionalAttr(PyObject \*obj, PyObject \*attr\_name, PyObject \*\*result)**](#int~30) See PyObject\_GetOptionalAttr() documentation <https://docs.python.org/dev/c-api/object.html#c.PyObject\_GetOptionalAttr>. [**int PyObject\_GetOptionalAttrString(PyObject \*obj, const char \*attr\_name, PyObject \*\*result)**](#int~31) See PyObject\_GetOptionalAttrString() documentation <https://docs.python.org/dev/c-api/object.html#c.PyObject\_GetOptionalAttrString>. [**int PyObject\_HasAttrWithError(PyObject \*obj, PyObject \*attr\_name)**](#int~32) See PyObject\_HasAttrWithError() documentation <https://docs.python.org/dev/c-api/object.html#c.PyObject\_HasAttrWithError>. [**int PyObject\_HasAttrStringWithError(PyObject \*obj, const char \*attr\_name)**](#int~33) See PyObject\_HasAttrStringWithError() documentation <https://docs.python.org/dev/c-api/object.html#c.PyObject\_HasAttrStringWithError>. [**int PyMapping\_GetOptionalItem(PyObject \*obj, PyObject \*key, PyObject \*\*result)**](#int~34) See PyMapping\_GetOptionalItem() documentation <https://docs.python.org/dev/c-api/mapping.html#c.PyMapping\_GetOptionalItem>. [**int PyMapping\_GetOptionalItemString(PyObject \*obj, const char \*key, PyObject \*\*result)**](#int~35) See PyMapping\_GetOptionalItemString() documentation <https://docs.python.org/dev/c-api/mapping.html#c.PyMapping\_GetOptionalItemString>. [**int PyMapping\_HasKeyWithError(PyObject \*obj, PyObject \*key)**](#int~36) See PyMapping\_HasKeyWithError() documentation <https://docs.python.org/dev/c-api/mapping.html#c.PyMapping\_HasKeyWithError>. [**int PyMapping\_HasKeyStringWithError(PyObject \*obj, const char \*key)**](#int~37) See PyMapping\_HasKeyStringWithError() documentation <https://docs.python.org/dev/c-api/mapping.html#c.PyMapping\_HasKeyStringWithError>. [**int PyModule\_Add(PyObject \*module, const char \*name, PyObject \*value)**](#int~38) See PyModule\_Add() documentation <https://docs.python.org/dev/c-api/module.html#c.PyModule\_Add>. [**int PyWeakref\_GetRef(PyObject \*ref, PyObject \*\*pobj)**](#int~39) See PyWeakref\_GetRef() documentation <https://docs.python.org/dev/c-api/weakref.html#c.PyWeakref\_GetRef>. [**int Py\_IsFinalizing()**](#int~40) 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 <https://docs.python.org/dev/c-api/init.html#c.Py\_IsFinalizing>. [**int PyDict\_ContainsString(PyObject \*p, const char \*key)**](#int~41) See PyDict\_ContainsString() documentation <https://docs.python.org/dev/c-api/dict.html#c.PyDict\_ContainsString>. [**int PyLong\_AsInt(PyObject \*obj)**](#int~42) See PyLong\_AsInt() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong\_AsInt>. [**int PyObject\_VisitManagedDict(PyObject \*obj, visitproc visit, void \*arg)**](#int~43) See PyObject\_VisitManagedDict() documentation <https://docs.python.org/dev/c-api/object.html#c.PyObject\_VisitManagedDict>. [**void PyObject\_ClearManagedDict(PyObject \*obj)**](#void~8) See PyObject\_ClearManagedDict() documentation <https://docs.python.org/dev/c-api/object.html#c.PyObject\_ClearManagedDict>. **PyThreadState \*PyThreadState\_GetUnchecked(void)** See PyThreadState\_GetUnchecked() documentation <https://docs.python.org/dev/c-api/init.html#c.PyThreadState\_GetUnchecked>. Available on Python 3.5.2 and newer. [**int PyUnicode\_EqualToUTF8(PyObject \*unicode, const char \*str)**](#int~44) See PyUnicode\_EqualToUTF8() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicode\_EqualToUTF8>. [**int PyUnicode\_EqualToUTF8AndSize(PyObject \*unicode, const char \*str, Py\_ssize\_t size)**](#int~45) See PyUnicode\_EqualToUTF8AndSize() documentation <https://docs.python.org/dev/c-api/unicode.html#c.PyUnicode\_EqualToUTF8AndSize>. [**int PyList\_Extend(PyObject \*list, PyObject \*iterable)**](#int~46) See PyList\_Extend() documentation <https://docs.python.org/dev/c-api/list.html#c.PyList\_Extend>. [**int PyList\_Clear(PyObject \*list)**](#int~47) See PyList\_Clear() documentation <https://docs.python.org/dev/c-api/list.html#c.PyList\_Clear>. [**int PyDict\_Pop(PyObject \*dict, PyObject \*key, PyObject \*\*result)**](#int~48) See PyDict\_Pop() documentation <https://docs.python.org/dev/c-api/dict.html#c.PyDict\_Pop>. [**int PyDict\_PopString(PyObject \*dict, const char \*key, PyObject \*\*result)**](#int~49) See PyDict\_PopString() documentation <https://docs.python.org/dev/c-api/dict.html#c.PyDict\_PopString>. [**Py\_hash\_t Py\_HashPointer(const void \*ptr)**](#Py_hash_t~3) See Py\_HashPointer() documentation <https://docs.python.org/dev/c-api/hash.html#c.Py\_HashPointer>. [**type PyTime\_t**](#type) A timestamp or duration in nanoseconds, represented as a signed 64-bit integer. [**PyTime\_t <#c.PyTime\_t> PyTime\_MIN**](#PyTime_t) Minimum value of **PyTime\_t**. [**PyTime\_t <#c.PyTime\_t> PyTime\_MAX**](#PyTime_t~2) Maximum value of **PyTime\_t**. [**double PyTime\_AsSecondsDouble(PyTime\_t <#c.PyTime\_t> t)**](#double) See PyTime\_AsSecondsDouble() documentation <https://docs.python.org/dev/c-api/time.html#c.PyTime\_AsSecondsDouble>. [**int PyTime\_Monotonic(PyTime\_t <#c.PyTime\_t> \*result)**](#int~50) See PyTime\_Monotonic() documentation <https://docs.python.org/dev/c-api/time.html#c.PyTime\_Monotonic>. [**int PyTime\_Time(PyTime\_t <#c.PyTime\_t> \*result)**](#int~51) See PyTime\_Time() documentation <https://docs.python.org/dev/c-api/time.html#c.PyTime\_Time>. [**int PyTime\_PerfCounter(PyTime\_t <#c.PyTime\_t> \*result)**](#int~52) See PyTime\_PerfCounter() documentation <https://docs.python.org/dev/c-api/time.html#c.PyTime\_PerfCounter>. **PyObject \*PyList\_GetItemRef(PyObject \*op, Py\_ssize\_t index)** See PyList\_GetItemRef() documentation <https://docs.python.org/dev/c-api/list.html#c.PyList\_GetItemRef>. [**int PyDict\_SetDefaultRef(PyObject \*d, PyObject \*key, PyObject \*default\_value, PyObject \*\*result)**](#int~53) See PyDict\_SetDefaultRef() documentation <https://docs.python.org/dev/c-api/dict.html#c.PyDict\_SetDefaultRef>. Not supported: - **PyErr\_FormatUnraisable()**. - **PyLong\_AsNativeBytes()** - **PyLong\_FromNativeBytes()** - **PyLong\_FromUnsignedNativeBytes()** - **PyObject\_GenericHash()**. - **PySys\_Audit()**. - **PySys\_AuditTuple()**. - **PyType\_GetFullyQualifiedName()** - **PyType\_GetModuleName()** ## [Python 3.12](#Python_3.12) **PyObject \*PyFrame\_GetVar(PyFrameObject \*frame, PyObject \*name)** See PyFrame\_GetVar() documentation <https://docs.python.org/dev/c-api/frame.html#c.PyFrame\_GetVar>. Not available on PyPy. **PyObject \*PyFrame\_GetVarString(PyFrameObject \*frame, const char \*name)** See PyFrame\_GetVarString() documentation <https://docs.python.org/dev/c-api/frame.html#c.PyFrame\_GetVarString>. Not available on PyPy. **PyObject \*Py\_GetConstant(unsigned int constant\_id)** See Py\_GetConstant() documentation <https://docs.python.org/dev/c-api/object.html#c.Py\_GetConstant>. **PyObject \*Py\_GetConstantBorrowed(unsigned int constant\_id)** See Py\_GetConstantBorrowed() documentation <https://docs.python.org/dev/c-api/object.html#c.Py\_GetConstantBorrowed>. 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](#Python_3.11) **PyObject \*PyCode\_GetCellvars(PyCodeObject \*code)** See PyCode\_GetCellvars() documentation <https://docs.python.org/dev/c-api/code.html#c.PyCode\_GetCellvars>. Not available on PyPy. **PyObject \*PyCode\_GetCode(PyCodeObject \*code)** See PyCode\_GetCode() documentation <https://docs.python.org/dev/c-api/code.html#c.PyCode\_GetCode>. Not available on PyPy. **PyObject \*PyCode\_GetFreevars(PyCodeObject \*code)** See PyCode\_GetFreevars() documentation <https://docs.python.org/dev/c-api/code.html#c.PyCode\_GetFreevars>. Not available on PyPy. **PyObject \*PyCode\_GetVarnames(PyCodeObject \*code)** See PyCode\_GetVarnames() documentation <https://docs.python.org/dev/c-api/code.html#c.PyCode\_GetVarnames>. Not available on PyPy. **PyObject \*PyFrame\_GetBuiltins(PyFrameObject \*frame)** See PyFrame\_GetBuiltins() documentation <https://docs.python.org/dev/c-api/frame.html#c.PyFrame\_GetBuiltins>. Not available on PyPy. **PyObject \*PyFrame\_GetGlobals(PyFrameObject \*frame)** See PyFrame\_GetGlobals() documentation <https://docs.python.org/dev/c-api/frame.html#c.PyFrame\_GetGlobals>. Not available on PyPy. [**int PyFrame\_GetLasti(PyFrameObject \*frame)**](#int~54) See PyFrame\_GetLasti() documentation <https://docs.python.org/dev/c-api/frame.html#c.PyFrame\_GetLasti>. Not available on PyPy. **PyObject \*PyFrame\_GetLocals(PyFrameObject \*frame)** See PyFrame\_GetLocals() documentation <https://docs.python.org/dev/c-api/frame.html#c.PyFrame\_GetLocals>. Not available on PyPy. [**void PyThreadState\_EnterTracing(PyThreadState \*tstate)**](#void~9) See PyThreadState\_EnterTracing() documentation <https://docs.python.org/dev/c-api/init.html#c.PyThreadState\_EnterTracing>. Not available on PyPy. [**void PyThreadState\_LeaveTracing(PyThreadState \*tstate)**](#void~10) See PyThreadState\_LeaveTracing() documentation <https://docs.python.org/dev/c-api/init.html#c.PyThreadState\_LeaveTracing>. Not available on PyPy [**int PyFloat\_Pack2(double x, unsigned char \*p, int le)**](#int~55) 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)**](#int~56) 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)**](#int~57) 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)**](#double~2) 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)**](#double~3) 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)**](#double~4) 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](#Python_3.10) **PyObject \*Py\_NewRef(PyObject \*obj)** See Py\_NewRef() documentation <https://docs.python.org/dev/c-api/refcounting.html#c.Py\_NewRef>. **PyObject \*Py\_XNewRef(PyObject \*obj)** See Py\_XNewRef() documentation <https://docs.python.org/dev/c-api/refcounting.html#c.Py\_XNewRef>. [**int Py\_Is(PyObject \*x, PyObject \*y)**](#int~58) See Py\_Is() documentation <https://docs.python.org/dev/c-api/structures.html#c.Py\_Is>. [**int Py\_IsNone(PyObject \*x)**](#int~59) See Py\_IsNone() documentation <https://docs.python.org/dev/c-api/structures.html#c.Py\_IsNone>. [**int Py\_IsTrue(PyObject \*x)**](#int~60) See Py\_IsTrue() documentation <https://docs.python.org/dev/c-api/structures.html#c.Py\_IsTrue>. [**int Py\_IsFalse(PyObject \*x)**](#int~61) See Py\_IsFalse() documentation <https://docs.python.org/dev/c-api/structures.html#c.Py\_IsFalse>. [**int PyModule\_AddObjectRef(PyObject \*module, const char \*name, PyObject \*value)**](#int~62) See PyModule\_AddObjectRef() documentation <https://docs.python.org/dev/c-api/module.html#c.PyModule\_AddObjectRef>. 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](#Python_3.9) ## [PyObject](#PyObject) [**void Py\_SET\_REFCNT(PyObject \*ob, Py\_ssize\_t refcnt)**](#void~11) See Py\_SET\_REFCNT() documentation <https://docs.python.org/dev/c-api/structures.html#c.Py\_SET\_REFCNT>. [**void Py\_SET\_TYPE(PyObject \*ob, PyTypeObject \*type)**](#void~12) See Py\_SET\_TYPE() documentation <https://docs.python.org/dev/c-api/structures.html#c.Py\_SET\_TYPE>. [**void Py\_SET\_SIZE(PyVarObject \*ob, Py\_ssize\_t size)**](#void~13) See Py\_SET\_SIZE() documentation <https://docs.python.org/dev/c-api/structures.html#c.Py\_SET\_SIZE>. [**int Py\_IS\_TYPE(const PyObject \*ob, const PyTypeObject \*type)**](#int~63) See Py\_IS\_TYPE() documentation <https://docs.python.org/dev/c-api/structures.html#c.Py\_IS\_TYPE>. **PyObject \*PyObject\_CallNoArgs(PyObject \*func)** See PyObject\_CallNoArgs() documentation <https://docs.python.org/dev/c-api/call.html#c.PyObject\_CallNoArgs>. **PyObject \*PyObject\_CallOneArg(PyObject \*func, PyObject \*arg)** See PyObject\_CallOneArg() documentation <https://docs.python.org/dev/c-api/call.html#c.PyObject\_CallOneArg>. **PyObject \*PyObject\_Vectorcall(PyObject \*callable, PyObject \*const \*args, size\_t nargsf, PyObject \*kwnames)** See PyObject\_Vectorcall() documentation <https://docs.python.org/dev/c-api/call.html#c.PyObject\_Vectorcall>. [**Py\_ssize\_t PyVectorcall\_NARGS(size\_t nargsf)**](#Py_ssize_t~2) See PyVectorcall\_NARGS() documentation <https://docs.python.org/dev/c-api/call.html#c.PyVectorcall\_NARGS>. [**PY\_VECTORCALL\_ARGUMENTS\_OFFSET**](#PY_VECTORCALL_ARGUMENTS_OFFSET) See PY\_VECTORCALL\_ARGUMENTS\_OFFSET documentation <https://docs.python.org/dev/c-api/call.html#PY\_VECTORCALL\_ARGUMENTS\_OFFSET>. Not supported: - **PyVectorcall\_CallMethod()**. - **PyType\_FromModuleAndSpec()** ## [PyFrameObject](#PyFrameObject) [**PyCodeObject \*PyFrame\_GetCode(PyFrameObject \*frame)**](#PyCodeObject) See PyFrame\_GetCode() documentation <https://docs.python.org/dev/c-api/reflection.html#c.PyFrame\_GetCode>. **PyFrameObject \*PyFrame\_GetBack(PyFrameObject \*frame)** See PyFrame\_GetBack() documentation <https://docs.python.org/dev/c-api/reflection.html#c.PyFrame\_GetBack>. Not available on PyPy ## [PyThreadState](#PyThreadState) **PyFrameObject \*PyThreadState\_GetFrame(PyThreadState \*tstate)** See PyThreadState\_GetFrame() documentation <https://docs.python.org/dev/c-api/init.html#c.PyThreadState\_GetFrame>. Not available on PyPy **PyInterpreterState \*PyThreadState\_GetInterpreter(PyThreadState \*tstate)** See PyThreadState\_GetInterpreter() documentation <https://docs.python.org/dev/c-api/init.html#c.PyThreadState\_GetInterpreter>. [**uint64\_t PyThreadState\_GetID(PyThreadState \*tstate)**](#uint64_t) See PyThreadState\_GetID() documentation <https://docs.python.org/dev/c-api/init.html#c.PyThreadState\_GetID>. Availability: Python 3.7. Not available on PyPy. ## [PyInterpreterState](#PyInterpreterState) **PyInterpreterState \*PyInterpreterState\_Get(void)** See PyInterpreterState\_Get() documentation <https://docs.python.org/dev/c-api/init.html#c.PyInterpreterState\_Get>. ## [GC protocol](#GC_protocol) [**int PyObject\_GC\_IsTracked(PyObject \*obj)**](#int~64) See PyObject\_GC\_IsTracked() documentation <https://docs.python.org/dev/c-api/gcsupport.html#c.PyObject\_GC\_IsTracked>. Not available on PyPy. [**int PyObject\_GC\_IsFinalized(PyObject \*obj)**](#int~65) See PyObject\_GC\_IsFinalized() documentation <https://docs.python.org/dev/c-api/gcsupport.html#c.PyObject\_GC\_IsFinalized>. Availability: Python 3.4. Not available on PyPy. ## [Module helper](#Module_helper) [**int PyModule\_AddType(PyObject \*module, PyTypeObject \*type)**](#int~66) See PyModule\_AddType() documentation <https://docs.python.org/dev/c-api/module.html#c.PyModule\_AddType>. ## [Python 3.8](#Python_3.8) Not supported: • **PyCode\_NewWithPosOnlyArgs()**. ## [Python 3.7](#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](#Python_3.6) Not supported: - **PyErr\_ResourceWarning()**. - **PyErr\_SetImportErrorSubclass()**. - **PyOS\_FSPath()**. - **Py\_FinalizeEx()**. ## [Python 3.5.2](#Python_3.5.2) [**Py\_SETREF(op, op2)**](#Py_SETREF%28op,) [**Py\_XSETREF(op, op2)**](#Py_XSETREF%28op,) Not supported: - **PyCodec\_NameReplaceErrors()**. - **PyErr\_FormatV()**. - **PyExc\_RecursionError**. - **PyModule\_FromDefAndSpec()**, **PyModule\_FromDefAndSpec2()**, and **PyModule\_ExecDef()**. - **PyNumber\_MatrixMultiply()** and **PyNumber\_InPlaceMatrixMultiply()**. ## [Python 3.4](#Python_3.4) [**Py\_UNUSED(name)**](#Py_UNUSED%28name%29) See Py\_UNUSED() documentation <https://docs.python.org/dev/c-api/intro.html#c.Py\_UNUSED>. ## [Python 3.2](#Python_3.2) Not supported: - **Py\_VA\_COPY**. - **PySys\_SetArgvEx()**. - **PyLong\_AsLongLongAndOverflow()**. - **PyErr\_NewExceptionWithDoc()**. ## [Python 3.1](#Python_3.1) Not supported: - **PyOS\_string\_to\_double()**. - **PyCapsule** API. ## [Borrow variant](#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)**](#PyCodeObject~2) **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 USERS](#PYTHONCAPI-COMPAT_USERS) ## [Examples of projects using pythoncapi\_compat.h](#Examples_of_projects_using_pythoncapi_compat.h) - bitarray <https://github.com/ilanschnell/bitarray/>: **bitarray/\_bitarray.c** uses **Py\_SET\_SIZE()** (pythoncapi\_compat.h copy <https://github.com/ilanschnell/bitarray/blob/master/bitarray/pythoncapi\_compat.h>) - datatable <https://github.com/h2oai/datatable> (commit <https://github.com/h2oai/datatable/commit/02f13114828ed4567e4410f5bac579895e20355a>) - guppy3 <https://github.com/zhuyifei1999/guppy3/> (commit <https://github.com/zhuyifei1999/guppy3/commit/4cb9fcb5d75327544a6875b6caabfdffb70a7e29>) - immutables <https://github.com/MagicStack/immutables/>: **immutables/\_map.c** uses **Py\_SET\_SIZE()** (pythoncapi\_compat.h copy <https://github.com/MagicStack/immutables/blob/master/immutables/pythoncapi\_compat.h>) - Mercurial (hg) <https://www.mercurial-scm.org/> uses **Py\_SET\_TYPE()** (commit <https://www.mercurial-scm.org/repo/hg/rev/e92ca942ddca>, pythoncapi\_compat.h copy <https://www.mercurial-scm.org/repo/hg/file/tip/mercurial/pythoncapi\_compat.h>) - mypy <https://github.com/python/mypy> (mypyc, commit <https://github.com/python/mypy/commit/2b7e2df923f7e4a3a199915b3c8563f45bc69dfa>) - numpy <https://numpy.org/>: pythoncapi-compat Git submodule <https://github.com/numpy/numpy/blob/main/.gitmodules> - pybluez <https://github.com/pybluez/pybluez> (commit <https://github.com/pybluez/pybluez/commit/5096047f90a1f6a74ceb250aef6243e144170f92>) - python-snappy <https://github.com/andrix/python-snappy/> (commit <https://github.com/andrix/python-snappy/commit/1a539d71d5b1ceaf9a2291f21f686cf53a46d707>) - python-zstandard <https://github.com/indygreg/python-zstandard/> uses **Py\_SET\_TYPE()** and **Py\_SET\_SIZE()** (commit <https://github.com/indygreg/python-zstandard/commit/e5a3baf61b65f3075f250f504ddad9f8612bfedf>): Mercurial extension. - python-zstd <https://github.com/sergey-dryabzhinsky/python-zstd/> (commit <https://github.com/sergey-dryabzhinsky/python-zstd/commit/8aa6d7a4b250e1f0a4e27b4107c39dc516c87f96>) - hollerith <https://github.com/pyansys/hollerith/> **src/writer.c** uses **PyObject\_CallOneArg() and other Python 3.9 apis** (pythoncapi\_compat.h copy <https://github.com/pyansys/hollerith/blob/main/src/pythoncapi\_compat.h>) - PyTorch <https://github.com/pytorch/pytorch/> (pythoncapi\_compat.h copy <https://github.com/pytorch/pytorch/blob/main/torch/csrc/utils/pythoncapi\_compat.h>) - PyGObject <https://gitlab.gnome.org/GNOME/pygobject/> (commit <https://gitlab.gnome.org/GNOME/pygobject/-/commit/074c0348417b87d3003dbb409e6fc26b61121de3>, pythoncapi-compat Meson subproject <https://gitlab.gnome.org/GNOME/pygobject/-/blob/main/subprojects/pythoncapi-compat.wrap?ref\_type=heads>) - Pillow <https://github.com/python-pillow/Pillow/> (src/thirdparty/pythoncapi\_compat.h <https://github.com/python-pillow/Pillow/blob/main/src/thirdparty/pythoncapi\_compat.h>) - watchdog <https://github.com/gorakhargosh/watchdog/> (src/pythoncapi\_compat.h <https://github.com/gorakhargosh/watchdog/blob/master/src/pythoncapi\_compat.h>) ## [Projects not using pythoncapi\_compat.h](#Projects_not_using_pythoncapi_compat.h) Projects not using **pythoncapi\_compat.h**: • Cython doesn't use pythoncapi\_compat.h: see Cython issue #3934 <https://github.com/cython/cython/issues/3934>. For example, ModuleSetupCode.c <https://github.com/cython/cython/blob/0.29.x/Cython/Utility/ModuleSetupCode.c> provides functions like **\_\_Pyx\_SET\_REFCNT()**. Project with a strict contributor agreement: • zodbpickle <https://github.com/zopefoundation/zodbpickle/pull/64> # [RUN TESTS](#RUN_TESTS) To run pythoncapi-compat tests, type: ``` python3 runtests.py ``` To only test the current Python version, use the **-c** or the **--current** option: ``` python3 runtests.py --current ``` Verbose mode (**-v**, **--verbose**): ``` python3 runtests.py --verbose ``` See tests in the **tests/** subdirectory. # [CHANGELOG](#CHANGELOG) - 2026-09-23: **PyUnstable\_Object\_IsUniquelyReferenced()**, **PyUnstable\_TryIncRef()** and **PyUnstable\_EnableTryIncRef()** are no longer available on PyPy. **Py\_REFCNT()** semantics is different on PyPy. - 2026-09-22: Add support for PyPy3.12 v8.0.0, which provides **PyFrame\_GetCode()** and **PyInterpreterState\_Get()**. - 2026-09-07: Remove code to support Python 2.7, Python 3.5 and PyPy for Python 2.7 ("pypy2"). Python 2.7 was no longer supported since August 2023. Python 3.5 was no longer supported since October 2024. - 2026-02-12: Add functions: • **PyUnstable\_SetImmortal()** • 2025-10-14: Add functions: - **PyTuple\_FromArray()** - **PyUnstable\_Unicode\_GET\_CACHED\_HASH()** • 2025-09-18: Add PEP 782 functions: - **PyBytesWriter\_Create()** - **PyBytesWriter\_Discard()** - **PyBytesWriter\_Finish()** - **PyBytesWriter\_FinishWithPointer()** - **PyBytesWriter\_FinishWithSize()** - **PyBytesWriter\_Format()** - **PyBytesWriter\_GetData()** - **PyBytesWriter\_GetSize()** - **PyBytesWriter\_Grow()** - **PyBytesWriter\_GrowAndUpdatePointer()** - **PyBytesWriter\_Resize()** - **PyBytesWriter\_WriteBytes()** - 2025-09-01: Add **PyUnstable\_Object\_IsUniquelyReferenced()** function. - 2025-06-09: Add **PyUnicodeWriter\_WriteASCII()** function. - 2025-06-03: Add functions: - **PySys\_GetAttr()** - **PySys\_GetAttrString()** - **PySys\_GetOptionalAttr()** - **PySys\_GetOptionalAttrString()** - 2025-01-19: Add **PyConfig\_Get()** functions. - 2025-01-06: Add **Py\_fopen()** and **Py\_fclose()** functions. - 2024-12-16: Add **structmember.h** constants: - **Py\_T\_BOOL** - **Py\_T\_BYTE** - **Py\_T\_CHAR** - **Py\_T\_DOUBLE** - **Py\_T\_FLOAT** - **Py\_T\_INT** - **Py\_T\_LONGLONG** - **Py\_T\_LONG** - **Py\_T\_OBJECT\_EX** - **Py\_T\_PYSSIZET** - **Py\_T\_SHORT** - **Py\_T\_STRING\_INPLACE** - **Py\_T\_STRING** - **Py\_T\_UBYTE** - **Py\_T\_UINT** - **Py\_T\_ULONGLONG** - **Py\_T\_ULONG** - **Py\_T\_USHORT** - **\_Py\_T\_NONE** - **\_Py\_T\_OBJECT** - **Py\_AUDIT\_READ** - **Py\_READONLY** - **\_Py\_WRITE\_RESTRICTED** • 2024-12-13: Add functions and structs: - **PyLongLayout** - **PyLong\_GetNativeLayout()** - **PyLongExport** - **PyLong\_Export()** - **PyLong\_FreeExport()** - **PyLongWriter** - **PyLongWriter\_Create()** - **PyLongWriter\_Finish()** - **PyLongWriter\_Discard()** • 2024-11-12: Add functions: - **PyLong\_IsPositive()** - **PyLong\_IsNegative()** - **PyLong\_IsZero()** • 2024-10-09: Add functions: - **PyBytes\_Join()** - **PyIter\_NextItem()** - **PyLong\_AsInt32()** - **PyLong\_AsInt64()** - **PyLong\_AsUInt32()** - **PyLong\_AsUInt64()** - **PyLong\_FromInt32()** - **PyLong\_FromInt64()** - **PyLong\_FromUInt32()** - **PyLong\_FromUInt64()** - **PyUnicode\_Equal()** - **Py\_HashBuffer()** • 2024-07-18: Add functions: - **PyUnicodeWriter\_Create()** - **PyUnicodeWriter\_Discard()** - **PyUnicodeWriter\_Finish()** - **PyUnicodeWriter\_WriteChar()** - **PyUnicodeWriter\_WriteUTF8()** - **PyUnicodeWriter\_WriteStr()** - **PyUnicodeWriter\_WriteRepr()** - **PyUnicodeWriter\_WriteSubstring()** - **PyUnicodeWriter\_WriteWideChar()** - **PyUnicodeWriter\_Format()** - 2024-06-03: Add **PyLong\_GetSign()**. - 2024-04-23: Drop Python 3.5 support. It cannot be tested anymore (pip fails). - 2024-04-02: Add **PyDict\_SetDefaultRef()** function. - 2024-03-29: Add **PyList\_GetItemRef()** function. - 2024-03-21: Add functions: - **Py\_GetConstant()** - **Py\_GetConstantBorrowed()** • 2024-03-09: Add hash constants: - **PyHASH\_BITS** - **PyHASH\_IMAG** - **PyHASH\_INF** - **PyHASH\_MODULUS** • 2024-02-20: Add PyTime API: - **PyTime\_t** type - **PyTime\_MIN** and **PyTime\_MAX** constants - **PyTime\_AsSecondsDouble()** - **PyTime\_Monotonic()** - **PyTime\_PerfCounter()** - **PyTime\_Time()** - 2023-12-15: Add function **Py\_HashPointer()**. - 2023-11-14: Add functions: - **PyDict\_Pop()** - **PyDict\_PopString()** • 2023-11-13: Add functions: - **PyList\_Extend()** - **PyList\_Clear()** • 2023-10-04: Add functions: - **PyUnicode\_EqualToUTF8()** - **PyUnicode\_EqualToUTF8AndSize()** • 2023-10-03: Add functions: - **PyObject\_VisitManagedDict()** - **PyObject\_ClearManagedDict()** - **PyThreadState\_GetUnchecked()** • 2023-09-29: Add functions: - **PyMapping\_HasKeyWithError()** - **PyMapping\_HasKeyStringWithError()** - **PyObject\_HasAttrWithError()** - **PyObject\_HasAttrStringWithError()** - 2023-08-25: Add **PyDict\_ContainsString()** and **PyLong\_AsInt()** functions. - 2023-08-21: Remove support for Python 2.7, Python 3.4 and older. - 2023-08-16: Add **Py\_IsFinalizing()** function. - 2023-07-21: Add **PyDict\_GetItemRef()** function. - 2023-07-18: Add **PyModule\_Add()** function. - 2023-07-12: Add functions: - **PyObject\_GetOptionalAttr()** - **PyObject\_GetOptionalAttrString()** - **PyMapping\_GetOptionalItem()** - **PyMapping\_GetOptionalItemString()** - 2023-07-05: Add **PyObject\_Vectorcall()** function. - 2023-06-21: Add **PyWeakref\_GetRef()** function. - 2023-06-20: Add **PyImport\_AddModuleRef()** function. - 2022-11-15: Add experimental operations to the **upgrade\_pythoncapi.py** script: **Py\_NewRef**, **Py\_CLEAR** and **Py\_SETREF**. - 2022-11-09: Fix **Py\_SETREF()** and **Py\_XSETREF()** macros for gh-98724 <https://github.com/python/cpython/issues/98724>. - 2022-11-04: Add **PyFrame\_GetVar()** and **PyFrame\_GetVarString()** functions. - 2022-08-04: Add **PyCode\_GetVarnames()**, **PyCode\_GetFreevars()** and **PyCode\_GetCellvars()** functions. - 2022-06-14: Fix compatibility with C++ older than C++11. - 2022-05-03: Add **PyCode\_GetCode()** function. - 2022-04-26: Rename the project from **pythoncapi\_compat** to **pythoncapi-compat**: replace the underscore separator with a dash. - 2022-04-08: Add functions **PyFrame\_GetLocals()**, **PyFrame\_GetGlobals()** **PyFrame\_GetBuiltins()**, and **PyFrame\_GetLasti()**. - 2022-03-12: Add functions **PyFloat\_Pack2()**, **PyFloat\_Pack4()**, **PyFloat\_Pack8()**, **PyFloat\_Unpack2()**, **PyFloat\_Unpack4()** and **PyFloat\_Unpack8()**. - 2022-03-03: The project moved to <https://github.com/python/pythoncapi-compat> - 2022-02-11: The project license changes from the MIT license to the Zero Clause BSD (0BSD) license. Projects copying **pythoncapi\_compat.h** no longer have to include the MIT license and the copyright notice. - 2022-02-08: Add documentation. - 2022-02-09: **pythoncapi\_compat.h** now supports C++ on Python 3.6 and newer: use **nullptr** and **reinterpret\_cast<type>** cast on C++, and use **NULL** and **(type)** cast on C. - 2021-10-15: Add **PyThreadState\_EnterTracing()** and **PyThreadState\_LeaveTracing()**. - 2021-04-09: Add **Py\_Is()**, **Py\_IsNone()**, **Py\_IsTrue()**, **Py\_IsFalse()** functions. - 2021-04-01: - Add **Py\_SETREF()**, **Py\_XSETREF()** and **Py\_UNUSED()**. - Add PyPy support. - 2021-01-27: Fix compatibility with Visual Studio 2008 for Python 2.7. - 2020-11-30: Creation of the **upgrade\_pythoncapi.py** script. - 2020-06-04: Creation of the **pythoncapi\_compat.h** header file. # [LINKS](#LINKS) - Python/C API Reference Manual <https://docs.python.org/dev/c-api/> - HPy: a better API for Python <https://hpy.readthedocs.io/> - Cython: C-extensions for Python <https://cython.org/> - Old 2to3c project <https://github.com/davidmalcolm/2to3c> by David Malcolm which uses Coccinelle <https://coccinelle.gitlabpages.inria.fr/website/> to ease migration of C extensions from Python 2 to Python 3. See also 2to3c: an implementation of Python's 2to3 for C code <https://dmalcolm.livejournal.com/3935.html> article (2009). - PEPs related to the C API: - PEP 620 -- Hide implementation details from the C API <https://www.python.org/dev/peps/pep-0620/> - PEP 670 -- Convert macros to functions in the Python C API <https://www.python.org/dev/peps/pep-0670/> - PEP 674 -- Disallow using macros as l-values <https://www.python.org/dev/peps/pep-0674/> • Make structures opaque - bpo-39573: PyObject <https://bugs.python.org/issue39573> - bpo-40170: PyTypeObject <https://bugs.python.org/issue40170> - bpo-39947: PyThreadState <https://bugs.python.org/issue39947> - bpo-40421: PyFrameObject <https://bugs.python.org/issue40421> - bpo-47241: PyCodeObject <https://bugs.python.org/issue47241> This project is distributed under the Zero Clause BSD (0BSD) license <https://opensource.org/licenses/0BSD> and is covered by the PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>. # [Author](#Author) Victor Stinner # [Copyright](#Copyright) 2022, Victor Stinner September 29, 2026 --- Document: pythoncapi_compat(1) from pythoncapi-compat 0_git20260929-r0 (Chainguard OS) Source: https://github.com/python/pythoncapi-compat.git