mirror of https://github.com/python/cpython
69 lines
2.2 KiB
ReStructuredText
69 lines
2.2 KiB
ReStructuredText
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.
|