From a3f515dd16b8f714678abe5416cf20d28b9473da Mon Sep 17 00:00:00 2001 From: Harshit Sharma <66710144+harshitethic@users.noreply.github.com> Date: Fri, 25 Sep 2026 11:13:32 +0530 Subject: [PATCH 1/4] docs: explain API and ABI differences --- source/guides/packaging-binary-extensions.rst | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index de8a9d2d6d..67ff38383b 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -147,11 +147,22 @@ also be considered: Alternatives to handcoded wrapper modules ----------------------------------------- -The C ABI (Application Binary Interface) is a common standard for sharing -functionality between multiple applications. One of the strengths of the -CPython C API (Application Programming Interface) is allowing Python users -to tap into that functionality. However, wrapping modules by hand is quite -tedious, so a number of other alternative approaches should be considered. +The C API (Application Programming Interface) is the source-level +contract used when compiling code: it defines functions, types, constants, +and how callers use them. The C ABI (Application Binary Interface) is the +corresponding binary-level contract used by already-compiled code, including +details such as exported symbols, calling conventions, and data layout. + +CPython exposes a rich C API, but extensions built against the full API are +normally tied to the CPython minor version and platform they were compiled +for because the full ABI is not stable across minor releases. Extensions +that only use CPython's Limited API can instead target the +:ref:`Stable ABI `, which allows a single ``abi3`` wheel +to work across multiple Python 3 minor versions on the same platform. + +These interfaces make it possible for Python users to tap into native +libraries. However, wrapping modules by hand is quite tedious, so a number +of other alternative approaches should be considered. The approaches described below don't simplify the distribution case at all, but they *can* significantly reduce the maintenance burden of keeping From d1ffa35ec8541324c1909a374b46a0835c2aa0bb Mon Sep 17 00:00:00 2001 From: Harshit Sharma <66710144+harshitethic@users.noreply.github.com> Date: Sat, 10 Oct 2026 21:31:10 +0530 Subject: [PATCH 2/4] docs: move binary extension API/ABI overview to general section --- source/guides/packaging-binary-extensions.rst | 35 ++++++++++--------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index 67ff38383b..6be2cf942d 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -102,6 +102,22 @@ zipfiles) often won't work for extension modules (as the dynamic loading mechanisms on most platforms can only load libraries from disk). +How binary extension modules work +--------------------------------- + +The C API (Application Programming Interface) is the source-level +contract used when compiling code: it defines functions, types, constants, +and how callers use them. The C ABI (Application Binary Interface) is the +corresponding binary-level contract used by already-compiled code, including +details such as exported symbols, calling conventions, and data layout. + +CPython exposes a rich C API, but extensions built against the full API are +normally tied to the CPython minor version and platform they were compiled +for because the full ABI is not stable across minor releases. Extensions +that only use CPython's Limited API can instead target the +:ref:`Stable ABI `, which allows a single ``abi3`` wheel +to work across multiple Python 3 minor versions on the same platform. + Alternatives to handcoded accelerator modules --------------------------------------------- @@ -147,22 +163,9 @@ also be considered: Alternatives to handcoded wrapper modules ----------------------------------------- -The C API (Application Programming Interface) is the source-level -contract used when compiling code: it defines functions, types, constants, -and how callers use them. The C ABI (Application Binary Interface) is the -corresponding binary-level contract used by already-compiled code, including -details such as exported symbols, calling conventions, and data layout. - -CPython exposes a rich C API, but extensions built against the full API are -normally tied to the CPython minor version and platform they were compiled -for because the full ABI is not stable across minor releases. Extensions -that only use CPython's Limited API can instead target the -:ref:`Stable ABI `, which allows a single ``abi3`` wheel -to work across multiple Python 3 minor versions on the same platform. - -These interfaces make it possible for Python users to tap into native -libraries. However, wrapping modules by hand is quite tedious, so a number -of other alternative approaches should be considered. +Binary extensions let Python programs use existing native libraries. +However, maintaining handcoded wrapper modules is tedious, so alternative +approaches should be considered. The approaches described below don't simplify the distribution case at all, but they *can* significantly reduce the maintenance burden of keeping From 38f23069f5e936464c98dd43b6f01b04c203faa4 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Tue, 27 Oct 2026 17:28:05 +1000 Subject: [PATCH 3/4] Prefer "feature release" to "minor version" Co-authored-by: Alyssa Coghlan --- source/guides/packaging-binary-extensions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index 6be2cf942d..73d8c4377a 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -112,9 +112,9 @@ corresponding binary-level contract used by already-compiled code, including details such as exported symbols, calling conventions, and data layout. CPython exposes a rich C API, but extensions built against the full API are -normally tied to the CPython minor version and platform they were compiled -for because the full ABI is not stable across minor releases. Extensions -that only use CPython's Limited API can instead target the +normally tied to the CPython feature release and platform they were compiled +against because the full ABI is not stable across feature releases. +Extensions that only use CPython's Limited API can instead target the :ref:`Stable ABI `, which allows a single ``abi3`` wheel to work across multiple Python 3 minor versions on the same platform. From 971bf2f9bfcddf3b692ccc9fc88b52da26a72a64 Mon Sep 17 00:00:00 2001 From: Alyssa Coghlan Date: Tue, 27 Oct 2026 17:29:20 +1000 Subject: [PATCH 4/4] Another minor version -> feature release tweak --- source/guides/packaging-binary-extensions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index 73d8c4377a..cd5f64fb54 100644 --- a/source/guides/packaging-binary-extensions.rst +++ b/source/guides/packaging-binary-extensions.rst @@ -116,7 +116,7 @@ normally tied to the CPython feature release and platform they were compiled against because the full ABI is not stable across feature releases. Extensions that only use CPython's Limited API can instead target the :ref:`Stable ABI `, which allows a single ``abi3`` wheel -to work across multiple Python 3 minor versions on the same platform. +to work across multiple Python 3 feature releases on the same platform. Alternatives to handcoded accelerator modules ---------------------------------------------