@@ -12,32 +12,36 @@ Include: Limited API and Stable ABI
1212===================================
1313
1414``Include/ ``, excluding the ``cpython `` and ``internal `` subdirectories,
15- contains the public Limited API and the Stable ABI. The Stable ABI is
16- defined by :pep: `384 `.
15+ contains the public Limited API (Application Programming Interface) and
16+ the Stable ABI (Application Binary Interface). :pep: `384 ` defined the
17+ Stable ABI and the Limited API; two related, but distinct concepts.
18+ The Stable ABI promises binary compatibility across subsequent versions of
19+ CPython 3.x, given that the source code restricts itself to the Limited
20+ API. The Limited API is a subset of the C API.
1721
18- *Note: * Functions stealing references or returning borrowed references
19- *must not * be added to the Limited API or the Stable ABI. A strong
20- reference *must * be returned. The API in ``Include/ `` should not expose
21- or leak implementation details.
22+ Guidelines for expanding the Limited API:
2223
23- Please start a public discussion before adding new functions or macros to
24- the Limited API.
25-
26- Functions or macros with a ``_Py `` prefix do not belong in ``Include/ ``.
24+ - Functions *must not * steal references
25+ - Functions *must not * return borrowed references
26+ - Functions returning references *must * return a strong reference
27+ - Macros should not expose implementation details
28+ - Please start a public discussion before expanding the API
29+ - Functions or macros with a ``_Py `` prefix do not belong in ``Include/ ``.
2730
2831
2932Include/cpython: CPython implementation details
3033===============================================
3134
3235``Include/cpython/ `` contains the public API that is excluded from the
33- Limited API and the Stable ABI. :pep: `384 ` introduced the
34- ``Py_LIMITED_API `` define to exclude functions from the Limited API.
35- When a new function or macro is introduced, it has to be explicitly
36- excluded using ``#ifndef Py_LIMITED_API ``.
36+ Limited API and the Stable ABI. When a new function or macro is
37+ introduced, it has to be explicitly excluded from the Limited API using
38+ ``#ifndef Py_LIMITED_API ``.
39+
40+ Guidelines for expanding the public API:
3741
38- * Note: * Functions stealing references or returning borrowed references
39- *must not * be added to `` Include/cpython/ ``. A strong reference * must *
40- be returned.
42+ - Functions * must not * steal references
43+ - Functions *must not * return borrowed references
44+ - Functions returning references * must * return a strong reference
4145
4246
4347Include/internal: The internal API
@@ -52,13 +56,13 @@ Functions or structures in ``Include/internal/`` defined with
5256exposed only for specific use cases like debuggers and profilers.
5357
5458
55- With extern keyword
56- -------------------
59+ With the extern keyword
60+ -----------------------
5761
58- Functions in ``Include/internal/ `` defined with ``extern `` * must not and can
59- not * be used outside the CPython code base. Only built-in stdlib
60- extensions (built with ``Py_BUILD_CORE_BUILTIN `` macro defined) can use
61- such functions.
62+ Functions in ``Include/internal/ `` defined with the ``extern `` keyword
63+ * must not and can not
64+ built-in stdlib extensions (built with the ``Py_BUILD_CORE_BUILTIN ``
65+ macro defined) can use such functions.
6266
6367When in doubt, new internal C functions should be defined in
64- ``Include/internal `` using ``extern ``.
68+ ``Include/internal `` using the ``extern `` keyword .
0 commit comments