gh-102304: doc: Add links to Stable ABI and Limited C API (#105345)

* Add "limited-c-api" and "stable-api" references.
* Rename "stable-abi-list" reference to "limited-api-list".
* Makefile: Document files regenerated by "make regen-limited-abi"
* Remove first empty line in generated files:

  - Lib/test/test_stable_abi_ctypes.py
  - PC/python3dll.c
This commit is contained in:
Victor Stinner 2023-06-06 10:40:32 +02:00 committed by GitHub
parent 00d73caf80
commit bae415ad02
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 58 additions and 42 deletions

View File

@ -887,7 +887,7 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
depth limit.
.. versionchanged:: 3.9
This function is now also available in the limited API.
This function is now also available in the :ref:`limited API <limited-c-api>`.
.. c:function:: void Py_LeaveRecursiveCall(void)
@ -895,7 +895,7 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
.. versionchanged:: 3.9
This function is now also available in the limited API.
This function is now also available in the :ref:`limited API <limited-c-api>`.
Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
special recursion handling. In addition to protecting the stack,

View File

@ -20,9 +20,9 @@ but will need to be compiled separately for 3.9.x and 3.10.x.
There are two tiers of C API with different stability exepectations:
- *Unstable API*, may change in minor versions without a deprecation period.
It is marked by the ``PyUnstable`` prefix in names.
- *Limited API*, is compatible across several minor releases.
- :ref:`Unstable API <unstable-c-api>`, may change in minor versions without
a deprecation period. It is marked by the ``PyUnstable`` prefix in names.
- :ref:`Limited API <limited-c-api>`, is compatible across several minor releases.
When :c:macro:`Py_LIMITED_API` is defined, only this subset is exposed
from ``Python.h``.
@ -55,19 +55,15 @@ CPython development and spend extra effort adjusting to changes.
Stable Application Binary Interface
===================================
.. _limited-c-api:
Limited C API
-------------
Python 3.2 introduced the *Limited API*, a subset of Python's C API.
Extensions that only use the Limited API can be
compiled once and work with multiple versions of Python.
Contents of the Limited API are :ref:`listed below <stable-abi-list>`.
To enable this, Python provides a *Stable ABI*: a set of symbols that will
remain compatible across Python 3.x versions. The Stable ABI contains symbols
exposed in the Limited API, but also other ones for example, functions
necessary to support older versions of the Limited API.
(For simplicity, this document talks about *extensions*, but the Limited API
and Stable ABI work the same way for all uses of the API for example,
embedding Python.)
Contents of the Limited API are :ref:`listed below <limited-api-list>`.
.. c:macro:: Py_LIMITED_API
@ -87,6 +83,23 @@ embedding Python.)
You can also define ``Py_LIMITED_API`` to ``3``. This works the same as
``0x03020000`` (Python 3.2, the version that introduced Limited API).
.. _stable-abi:
Stable ABI
----------
To enable this, Python provides a *Stable ABI*: a set of symbols that will
remain compatible across Python 3.x versions.
The Stable ABI contains symbols exposed in the :ref:`Limited API
<limited-c-api>`, but also other ones for example, functions necessary to
support older versions of the Limited API.
(For simplicity, this document talks about *extensions*, but the Limited API
and Stable ABI work the same way for all uses of the API for example,
embedding Python.)
On Windows, extensions that use the Stable ABI should be linked against
``python3.dll`` rather than a version-specific library such as
``python39.dll``.
@ -131,9 +144,9 @@ Limited API Caveats
-------------------
Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee that
code conforms to the Limited API or the Stable ABI. ``Py_LIMITED_API`` only
covers definitions, but an API also includes other issues, such as expected
semantics.
code conforms to the :ref:`Limited API <limited-c-api>` or the :ref:`Stable ABI
<stable-abi>`. ``Py_LIMITED_API`` only covers definitions, but an API also
includes other issues, such as expected semantics.
One issue that ``Py_LIMITED_API`` does not guard against is calling a function
with arguments that are invalid in a lower Python version.
@ -166,9 +179,9 @@ Platform Considerations
=======================
ABI stability depends not only on Python, but also on the compiler used,
lower-level libraries and compiler options. For the purposes of the Stable ABI,
these details define a “platform”. They usually depend on the OS
type and processor architecture
lower-level libraries and compiler options. For the purposes of
the :ref:`Stable ABI <stable-abi>`, these details define a “platform”. They
usually depend on the OS type and processor architecture
It is the responsibility of each particular distributor of Python
to ensure that all Python versions on a particular platform are built
@ -177,12 +190,12 @@ This is the case with Windows and macOS releases from ``python.org`` and many
third-party distributors.
.. _stable-abi-list:
.. _limited-api-list:
Contents of Limited API
=======================
Currently, the Limited API includes the following items:
Currently, the :ref:`Limited API <limited-c-api>` includes the following items:
.. limited-api-list::

View File

@ -288,7 +288,7 @@ There are these calling conventions:
.. versionchanged:: 3.10
``METH_FASTCALL`` is now part of the stable ABI.
``METH_FASTCALL`` is now part of the :ref:`stable ABI <stable-abi>`.
.. data:: METH_FASTCALL | METH_KEYWORDS

View File

@ -42,7 +42,7 @@ Type Objects
Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
meant for use with ``Py_LIMITED_API``; the individual flag bits are
guaranteed to be stable across Python releases, but access to
:c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
:c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited API <limited-c-api>`.
.. versionadded:: 3.2
@ -472,7 +472,7 @@ The following functions and structs are used to create
.. versionchanged:: 3.11
:c:member:`~PyBufferProcs.bf_getbuffer` and
:c:member:`~PyBufferProcs.bf_releasebuffer` are now available
under the limited API.
under the :ref:`limited API <limited-c-api>`.
.. c:member:: void *pfunc

View File

@ -2150,7 +2150,7 @@ This results in types that are limited relative to types defined in Python:
include any subinterpreter-specific state.
Also, since :c:type:`PyTypeObject` is only part of the :ref:`Limited API
<stable>` as an opaque struct, any extension modules using static types must be
<limited-c-api>` as an opaque struct, any extension modules using static types must be
compiled for a specific Python minor version.

View File

@ -994,7 +994,7 @@ These are the UTF-8 codec APIs:
The return type is now ``const char *`` rather of ``char *``.
.. versionchanged:: 3.10
This function is a part of the :ref:`limited API <stable>`.
This function is a part of the :ref:`limited API <limited-c-api>`.
.. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode)

View File

@ -461,7 +461,7 @@ Module State Access from Slot Methods, Getters and Setters
.. After adding to limited API:
If you use the :ref:`limited API <stable>,
If you use the :ref:`limited API <limited-c-api>`,
you must update ``Py_LIMITED_API`` to ``0x030b0000``, losing ABI
compatibility with earlier versions.

View File

@ -803,7 +803,7 @@ The :mod:`test.support` module defines the following functions:
.. decorator:: requires_limited_api
Decorator for only running the test if :ref:`Limited C API <stable>`
Decorator for only running the test if :ref:`Limited C API <limited-c-api>`
is available.

View File

@ -2650,7 +2650,7 @@ Removed
* :c:func:`PyMarshal_WriteObjectToString`
* the ``Py_MARSHAL_VERSION`` macro
These are not part of the :ref:`limited API <stable-abi-list>`.
These are not part of the :ref:`limited API <limited-api-list>`.
(Contributed by Victor Stinner in :issue:`45474`.)

View File

@ -1580,7 +1580,7 @@ New Features
(Contributed by Petr Viktorin in :gh:`103509`.)
* Added the new limited C API function :c:func:`PyType_FromMetaclass`,
* Added the new :ref:`limited C API <limited-c-api>` function :c:func:`PyType_FromMetaclass`,
which generalizes the existing :c:func:`PyType_FromModuleAndSpec` using
an additional metaclass argument.
(Contributed by Wenzel Jakob in :gh:`93012`.)

View File

@ -1,5 +1,4 @@
# Generated by Tools/scripts/stable_abi.py
# Generated by Tools/build/stable_abi.py
"""Test that all symbols of the Stable ABI are accessible using ctypes
"""

View File

@ -1309,6 +1309,11 @@ check-abidump: all
.PHONY: regen-limited-abi
regen-limited-abi: all
# Regenerate files using using Tools/build/stable_abi.py:
# - Doc/data/stable_abi.dat
# - Lib/test/test_stable_abi_ctypes.py
# - Modules/_testcapi_feature_macros.inc
# - PC/python3dll.c
$(RUNSHARED) ./$(BUILDPYTHON) $(srcdir)/Tools/build/stable_abi.py --generate-all $(srcdir)/Misc/stable_abi.toml
############################################################################

View File

@ -4980,7 +4980,7 @@ Removed documentation for the removed ``PyParser_*`` C API.
.. nonce: fy0AXK
.. section: C API
The list in :ref:`stable-abi-list` now shows the public name
The list in :ref:`limited-api-list` now shows the public name
:c:struct:`PyFrameObject` rather than ``_frame``. The non-existing entry
``_node`` no longer appears in the list.

View File

@ -1234,7 +1234,7 @@ defined:
* :c:func:`PyMarshal_WriteObjectToString`
* the ``Py_MARSHAL_VERSION`` macro
These are not part of the :ref:`limited API <stable-abi-list>`.
These are not part of the :ref:`limited API <limited-api-list>`.
Patch by Victor Stinner.

View File

@ -1,4 +1,4 @@
// Generated by Tools/scripts/stable_abi.py
// Generated by Tools/build/stable_abi.py
// Add an entry in dict `result` for each Stable ABI feature macro.

1
PC/python3dll.c generated
View File

@ -1,4 +1,3 @@
/* Re-export stable Python ABI */
/* Generated by Tools/build/stable_abi.py */

View File

@ -183,7 +183,7 @@ def generator(var_name, default_path):
def gen_python3dll(manifest, args, outfile):
"""Generate/check the source for the Windows stable ABI library"""
write = partial(print, file=outfile)
content = f"""
content = f"""\
/* Re-export stable Python ABI */
/* Generated by {SCRIPT_NAME} */
@ -267,8 +267,8 @@ def gen_doc_annotations(manifest, args, outfile):
def gen_ctypes_test(manifest, args, outfile):
"""Generate/check the ctypes-based test for exported symbols"""
write = partial(print, file=outfile)
write(textwrap.dedent('''
# Generated by Tools/scripts/stable_abi.py
write(textwrap.dedent(f'''\
# Generated by {SCRIPT_NAME}
"""Test that all symbols of the Stable ABI are accessible using ctypes
"""
@ -341,7 +341,7 @@ def gen_ctypes_test(manifest, args, outfile):
def gen_testcapi_feature_macros(manifest, args, outfile):
"""Generate/check the stable ABI list for documentation annotations"""
write = partial(print, file=outfile)
write('// Generated by Tools/scripts/stable_abi.py')
write(f'// Generated by {SCRIPT_NAME}')
write()
write('// Add an entry in dict `result` for each Stable ABI feature macro.')
write()