@@ -11,13 +11,14 @@ The C API is divided into three sections:
1111Include: Limited API and Stable ABI
1212===================================
1313
14- ``Include/ `` contains the public Limited API and the Stable ABI. The
15- Stable ABI is defined by :pep: `384 `.
14+ ``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 `.
1617
17- Functions stealing references or returning borrowed references * must not *
18- be added to the Limited API or the Stable ABI. A strong reference
19- *must * be returned. The API in ``Include/ `` should not expose or leak
20- implementation details.
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.
2122
2223Please start a public discussion before adding new functions or macros to
2324the Limited API.
@@ -29,16 +30,14 @@ Include/cpython: CPython implementation details
2930===============================================
3031
3132``Include/cpython/ `` contains the public API that is excluded from the
32- Limited API and Stable ABI. :pep: `384 ` introduced the `` Py_LIMITED_API ``
33- define to exclude functions from the Limited API. When a new function or
34- macro is introduced, it has to be explicitly excluded using
35- ``#ifndef Py_LIMITED_API ``.
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 ``.
3637
37- Functions stealing references or returning borrowed references *must not *
38- be added to ``Include/cpython/ ``. A strong reference *must * be
39- returned.
40-
41- See also `bpo-35134 <https://bugs.python.org/issue35134 >`_.
38+ *Note: * Functions stealing references or returning borrowed references
39+ *must not * be added to ``Include/cpython/ ``. A strong reference *must *
40+ be returned.
4241
4342
4443Include/internal: The internal API
@@ -48,18 +47,18 @@ Include/internal: The internal API
4847With PyAPI_FUNC or PyAPI_DATA
4948-----------------------------
5049
51- ``Include/internal/ `` functions or structures defined with `` PyAPI_FUNC ``
52- or ``PyAPI_DATA `` contains the internal API which is exposed for specific
53- use cases like debuggers and profilers.
50+ Functions or structures in ``Include/internal/ `` defined with
51+ `` PyAPI_FUNC `` or ``PyAPI_DATA `` are internal functions which are
52+ exposed only for specific use cases like debuggers and profilers.
5453
5554
5655With extern keyword
5756-------------------
5857
59- ``Include/internal/ `` function defined with ``extern `` *must not and can
58+ Functions in ``Include/internal/ `` defined with ``extern `` *must not and can
6059not * be used outside the CPython code base. Only built-in stdlib
6160extensions (built with ``Py_BUILD_CORE_BUILTIN `` macro defined) can use
62- it .
61+ such functions .
6362
64- In case of doubt, new internal functions must be defined in the internal
65- C API with ``extern ``.
63+ When in doubt, new internal C functions should be defined in
64+ `` Include/internal `` using ``extern ``.
0 commit comments