diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst index de8a9d2d6..6be2cf942 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,11 +163,9 @@ 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. +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