The C API is divided into three sections:
Include/
Include/cpython/
Include/internal/
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 inInclude/
.
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/
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
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.
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.