python / cpython

The Python C API

The C API is divided into three sections:

1. Include/
2. Include/cpython/
3. Include/internal/

Include: Limited API

Include/, excluding the cpython and internal subdirectories, contains the public Limited API (Application Programming Interface). The Limited API is a subset of the C API, designed to guarantee ABI stability across Python 3 versions, and is defined in PEP 384.

Guidelines for expanding the Limited API:

• Functions must not steal references
• Functions must not return borrowed references
• Functions returning references must return a strong reference
• Macros should not expose implementation details
• Please start a public discussion before expanding the API
• Functions or macros with a _Py prefix do not belong in Include/.

It is possible to add a function or macro to the Limited API from a given Python version. For example, to add a function to the Limited API from Python 3.10 and onwards, wrap it with #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000.

Include/cpython: CPython implementation details

Include/cpython/ contains the public API that is excluded from the Limited API and the Stable ABI.

Guidelines for expanding the public API:

• Functions must not steal references
• Functions must not return borrowed references
• Functions returning references must return a strong reference

Include/internal: The internal API

With PyAPI_FUNC or PyAPI_DATA

Functions or structures in Include/internal/ defined with PyAPI_FUNC or PyAPI_DATA are internal functions which are exposed only for specific use cases like debuggers and profilers.

With the extern keyword

Functions in Include/internal/ defined with the extern keyword must not and can not be used outside the CPython code base. Only built-in stdlib extensions (built with the Py_BUILD_CORE_BUILTIN macro defined) can use such functions.

When in doubt, new internal C functions should be defined in Include/internal using the extern keyword.