FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-102304: doc: Add links to Stable ABI and Limited C API (#105345) · python/cpython@bae415a · GitHub

/ cpython Public

Commit bae415a

Browse files
vstinner
authored
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
1 parent 00d73ca commit bae415a

17 files changed

Lines changed: 58 additions & 42 deletions

‎Doc/c-api/exceptions.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -887,15 +887,15 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
887887
depth limit.
888888
889889
.. versionchanged:: 3.9
890-
This function is now also available in the limited API.
890+
This function is now also available in the :ref:`limited API <limited-c-api>`.
891891
892892
.. c:function:: void Py_LeaveRecursiveCall(void)
893893
894894
Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
895895
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
896896
897897
.. versionchanged:: 3.9
898-
This function is now also available in the limited API.
898+
This function is now also available in the :ref:`limited API <limited-c-api>`.
899899
900900
Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
901901
special recursion handling. In addition to protecting the stack,

‎Doc/c-api/stable.rst‎

Lines changed: 34 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ but will need to be compiled separately for 3.9.x and 3.10.x.
2020

2121
There are two tiers of C API with different stability exepectations:
2222

23-
- *Unstable API*, may change in minor versions without a deprecation period.
24-
It is marked by the ``PyUnstable`` prefix in names.
25-
- *Limited API*, is compatible across several minor releases.
23+
- :ref:`Unstable API <unstable-c-api>`, may change in minor versions without
24+
a deprecation period. It is marked by the ``PyUnstable`` prefix in names.
25+
- :ref:`Limited API <limited-c-api>`, is compatible across several minor releases.
2626
When :c:macro:`Py_LIMITED_API` is defined, only this subset is exposed
2727
from ``Python.h``.
2828

@@ -55,19 +55,15 @@ CPython development and spend extra effort adjusting to changes.
5555
Stable Application Binary Interface
5656
===================================
5757

58+
.. _limited-c-api:
59+
60+
Limited C API
61+
-------------
62+
5863
Python 3.2 introduced the *Limited API*, a subset of Python's C API.
5964
Extensions that only use the Limited API can be
6065
compiled once and work with multiple versions of Python.
61-
Contents of the Limited API are :ref:`listed below <stable-abi-list>`.
62-
63-
To enable this, Python provides a *Stable ABI*: a set of symbols that will
64-
remain compatible across Python 3.x versions. The Stable ABI contains symbols
65-
exposed in the Limited API, but also other ones – for example, functions
66-
necessary to support older versions of the Limited API.
67-
68-
(For simplicity, this document talks about *extensions*, but the Limited API
69-
and Stable ABI work the same way for all uses of the API – for example,
70-
embedding Python.)
66+
Contents of the Limited API are :ref:`listed below <limited-api-list>`.
7167

7268
.. c:macro:: Py_LIMITED_API
7369
@@ -87,6 +83,23 @@ embedding Python.)
8783
You can also define ``Py_LIMITED_API`` to ``3``. This works the same as
8884
``0x03020000`` (Python 3.2, the version that introduced Limited API).
8985

86+
87+
.. _stable-abi:
88+
89+
Stable ABI
90+
----------
91+
92+
To enable this, Python provides a *Stable ABI*: a set of symbols that will
93+
remain compatible across Python 3.x versions.
94+
95+
The Stable ABI contains symbols exposed in the :ref:`Limited API
96+
<limited-c-api>`, but also other ones – for example, functions necessary to
97+
support older versions of the Limited API.
98+
99+
(For simplicity, this document talks about *extensions*, but the Limited API
100+
and Stable ABI work the same way for all uses of the API – for example,
101+
embedding Python.)
102+
90103
On Windows, extensions that use the Stable ABI should be linked against
91104
``python3.dll`` rather than a version-specific library such as
92105
``python39.dll``.
@@ -131,9 +144,9 @@ Limited API Caveats
131144
-------------------
132145

133146
Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee that
134-
code conforms to the Limited API or the Stable ABI. ``Py_LIMITED_API`` only
135-
covers definitions, but an API also includes other issues, such as expected
136-
semantics.
147+
code conforms to the :ref:`Limited API <limited-c-api>` or the :ref:`Stable ABI
148+
<stable-abi>`. ``Py_LIMITED_API`` only covers definitions, but an API also
149+
includes other issues, such as expected semantics.
137150

138151
One issue that ``Py_LIMITED_API`` does not guard against is calling a function
139152
with arguments that are invalid in a lower Python version.
@@ -166,9 +179,9 @@ Platform Considerations
166179
=======================
167180

168181
ABI stability depends not only on Python, but also on the compiler used,
169-
lower-level libraries and compiler options. For the purposes of the Stable ABI,
170-
these details define a “platform”. They usually depend on the OS
171-
type and processor architecture
182+
lower-level libraries and compiler options. For the purposes of
183+
the :ref:`Stable ABI <stable-abi>`, these details define a “platform”. They
184+
usually depend on the OS type and processor architecture
172185

173186
It is the responsibility of each particular distributor of Python
174187
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
177190
third-party distributors.
178191

179192

180-
.. _stable-abi-list:
193+
.. _limited-api-list:
181194

182195
Contents of Limited API
183196
=======================
184197

185198

186-
Currently, the Limited API includes the following items:
199+
Currently, the :ref:`Limited API <limited-c-api>` includes the following items:
187200

188201
.. limited-api-list::

‎Doc/c-api/structures.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,7 @@ There are these calling conventions:
288288
289289
.. versionchanged:: 3.10
290290
291-
``METH_FASTCALL`` is now part of the stable ABI.
291+
``METH_FASTCALL`` is now part of the :ref:`stable ABI <stable-abi>`.
292292
293293
294294
.. data:: METH_FASTCALL | METH_KEYWORDS

‎Doc/c-api/type.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ Type Objects
4242
Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
4343
meant for use with ``Py_LIMITED_API``; the individual flag bits are
4444
guaranteed to be stable across Python releases, but access to
45-
:c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
45+
:c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited API <limited-c-api>`.
4646
4747
.. versionadded:: 3.2
4848
@@ -472,7 +472,7 @@ The following functions and structs are used to create
472472
.. versionchanged:: 3.11
473473
:c:member:`~PyBufferProcs.bf_getbuffer` and
474474
:c:member:`~PyBufferProcs.bf_releasebuffer` are now available
475-
under the limited API.
475+
under the :ref:`limited API <limited-c-api>`.
476476
477477
.. c:member:: void *pfunc
478478

‎Doc/c-api/typeobj.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2150,7 +2150,7 @@ This results in types that are limited relative to types defined in Python:
21502150
include any subinterpreter-specific state.
21512151

21522152
Also, since :c:type:`PyTypeObject` is only part of the :ref:`Limited API
2153-
<stable>` as an opaque struct, any extension modules using static types must be
2153+
<limited-c-api>` as an opaque struct, any extension modules using static types must be
21542154
compiled for a specific Python minor version.
21552155

21562156

‎Doc/c-api/unicode.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -994,7 +994,7 @@ These are the UTF-8 codec APIs:
994994
The return type is now ``const char *`` rather of ``char *``.
995995
996996
.. versionchanged:: 3.10
997-
This function is a part of the :ref:`limited API <stable>`.
997+
This function is a part of the :ref:`limited API <limited-c-api>`.
998998
999999
10001000
.. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode)

‎Doc/howto/isolating-extensions.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -461,7 +461,7 @@ Module State Access from Slot Methods, Getters and Setters
461461

462462
.. After adding to limited API:
463463
464-
If you use the :ref:`limited API <stable>,
464+
If you use the :ref:`limited API <limited-c-api>`,
465465
you must update ``Py_LIMITED_API`` to ``0x030b0000``, losing ABI
466466
compatibility with earlier versions.
467467

‎Doc/library/test.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -803,7 +803,7 @@ The :mod:`test.support` module defines the following functions:
803803

804804
.. decorator:: requires_limited_api
805805

806-
Decorator for only running the test if :ref:`Limited C API <stable>`
806+
Decorator for only running the test if :ref:`Limited C API <limited-c-api>`
807807
is available.
808808

809809

‎Doc/whatsnew/3.11.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2650,7 +2650,7 @@ Removed
26502650
* :c:func:`PyMarshal_WriteObjectToString`
26512651
* the ``Py_MARSHAL_VERSION`` macro
26522652

2653-
These are not part of the :ref:`limited API <stable-abi-list>`.
2653+
These are not part of the :ref:`limited API <limited-api-list>`.
26542654

26552655
(Contributed by Victor Stinner in :issue:`45474`.)
26562656

‎Doc/whatsnew/3.12.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1580,7 +1580,7 @@ New Features
15801580

15811581
(Contributed by Petr Viktorin in :gh:`103509`.)
15821582

1583-
* Added the new limited C API function :c:func:`PyType_FromMetaclass`,
1583+
* Added the new :ref:`limited C API <limited-c-api>` function :c:func:`PyType_FromMetaclass`,
15841584
which generalizes the existing :c:func:`PyType_FromModuleAndSpec` using
15851585
an additional metaclass argument.
15861586
(Contributed by Wenzel Jakob in :gh:`93012`.)

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL