Skip to content

gh-127253: Note that Stable ABI is about ABI stability #127254

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

Merged
merged 1 commit into from
Dec 3, 2024
Merged

gh-127253: Note that Stable ABI is about ABI stability #127254

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 @@ -66,8 +66,8 @@

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.
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: PyCapsule_Type [ref.data]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be better to use ABI Compatible here instead of loaded on as the latter means that extension module can be loaded which may not be the case if the extension uses any function which now raises error while importing.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion.
This intro is meant to communicate the intent of the limited API, rather than give the precise description. I'd rather leave the term “ABI Compatible” to the sections below, which should also clear up which “multiple versions” the extension will work with.

Contents of the Limited API are :ref:`listed below <limited-api-list>`.

Check warning on line 70 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]

.. 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,8 +94,16 @@
----------

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 98 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]
.. 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: PyDictIterItem_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: PyDictIterKey_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: PyDictIterValue_Type [ref.data]
symbols or data corruption due to changes in structure layouts or function

Check warning on line 102 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]
signatures.
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: PyDictProxy_Type [ref.data]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be worth adding a small example here (e.g., reference counts, per the motivating issue).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think one example would do. Reference counts are less of a motivating issue and more of the straw that broke the camel's back.

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: PyDictRevIterItem_Type [ref.data]

Check warning on line 106 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
support older versions of the Limited API.
Expand Down
Loading