Skip to content

Explain the difference between C API and ABI #2145

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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
harshitethic wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Explain the difference between C API and ABI #2145

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a3f515d
docs: explain API and ABI differences
harshitethic Sep 25, 2026
d1ffa35
docs: move binary extension API/ABI overview to general section
harshitethic Oct 10, 2026
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
24 changes: 19 additions & 5 deletions source/guides/packaging-binary-extensions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <cpython-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
---------------------------------------------

Expand Down Expand Up @@ -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
Expand Down