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/2] 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/2] 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