Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[3.12] gh-127253: Note that Stable ABI is about ABI stability (GH-127254) #127558

Merged
merged 1 commit into from
Dec 3, 2024
Merged

[3.12] gh-127253: Note that Stable ABI is about ABI stability (GH-127254) #127558

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions Doc/c-api/stable.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@
-------------

Python 3.2 introduced the *Limited API*, a subset of Python's C API.
Extensions that only use the Limited API can be

Check warning on line 68 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyCapsule_Type [ref.data]
compiled once and work with multiple versions of Python.
compiled once and be loaded on multiple versions of Python.

Check warning on line 69 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyClassMethodDescr_Type [ref.data]
Contents of the Limited API are :ref:`listed below <limited-api-list>`.

.. c:macro:: Py_LIMITED_API
Expand All @@ -76,7 +76,7 @@

Define ``Py_LIMITED_API`` to the value of :c:macro:`PY_VERSION_HEX`
corresponding to the lowest Python version your extension supports.
The extension will work without recompilation with all Python 3 releases
The extension will be ABI-compatible with all Python 3 releases
from the specified one onward, and can use Limited API introduced up to that
version.

Expand All @@ -94,7 +94,15 @@
----------

To enable this, Python provides a *Stable ABI*: a set of symbols that will
remain compatible across Python 3.x versions.
remain ABI-compatible across Python 3.x versions.

Check warning on line 97 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyDictItems_Type [ref.data]

Check warning on line 98 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyDictIterItem_Type [ref.data]
.. note::

Check warning on line 99 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyDictIterKey_Type [ref.data]

Check warning on line 100 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyDictIterValue_Type [ref.data]
The Stable ABI prevents ABI issues, like linker errors due to missing

Check warning on line 101 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyDictKeys_Type [ref.data]
symbols or data corruption due to changes in structure layouts or function
signatures.

Check warning on line 103 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyDictProxy_Type [ref.data]
However, other changes in Python can change the *behavior* of extensions.

Check warning on line 104 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyDictRevIterItem_Type [ref.data]
See Python's Backwards Compatibility Policy (:pep:`387`) for details.

Check warning on line 105 in Doc/c-api/stable.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:data reference target not found: PyDictRevIterKey_Type [ref.data]

The Stable ABI contains symbols exposed in the :ref:`Limited API
<limited-c-api>`, but also other ones – for example, functions necessary to
Expand Down
Loading