[Python-checkins] bpo-43416: Add Include/README.rst (GH-24884)

[vstinner]

https://github.com/python/cpython/commit/929c9039fe0468cb37e0811ddfb7b67c98353ea8
commit: 929c9039fe0468cb37e0811ddfb7b67c98353ea8
branch: master
author: Erlend Egeberg Aasland <erlend.aasland at innova.no>
committer: vstinner <vstinner at python.org>
date: 2021-03-25T17:16:31+01:00
summary:

bpo-43416: Add Include/README.rst (GH-24884)

files:
A Include/README.rst

diff --git a/Include/README.rst b/Include/README.rst
new file mode 100644
index 0000000000000..d2467ca22fa03
--- /dev/null
+++ b/Include/README.rst
@@ -0,0 +1,68 @@
+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.