Skip to content

Commit a3f515d

Browse files
committed
docs: explain API and ABI differences
1 parent 457e74f commit a3f515d

1 file changed

Lines changed: 16 additions & 5 deletions

File tree

‎source/guides/packaging-binary-extensions.rst‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -147,11 +147,22 @@ also be considered:
147147
Alternatives to handcoded wrapper modules
148148
-----------------------------------------
149149

150-
The C ABI (Application Binary Interface) is a common standard for sharing
151-
functionality between multiple applications. One of the strengths of the
152-
CPython C API (Application Programming Interface) is allowing Python users
153-
to tap into that functionality. However, wrapping modules by hand is quite
154-
tedious, so a number of other alternative approaches should be considered.
150+
The C API (Application Programming Interface) is the source-level
151+
contract used when compiling code: it defines functions, types, constants,
152+
and how callers use them. The C ABI (Application Binary Interface) is the
153+
corresponding binary-level contract used by already-compiled code, including
154+
details such as exported symbols, calling conventions, and data layout.
155+
156+
CPython exposes a rich C API, but extensions built against the full API are
157+
normally tied to the CPython minor version and platform they were compiled
158+
for because the full ABI is not stable across minor releases. Extensions
159+
that only use CPython's Limited API can instead target the
160+
:ref:`Stable ABI <cpython-stable-abi>`, which allows a single ``abi3`` wheel
161+
to work across multiple Python 3 minor versions on the same platform.
162+
163+
These interfaces make it possible for Python users to tap into native
164+
libraries. However, wrapping modules by hand is quite tedious, so a number
165+
of other alternative approaches should be considered.
155166

156167
The approaches described below don't simplify the distribution case at all,
157168
but they *can* significantly reduce the maintenance burden of keeping

0 commit comments

Comments
 (0)