Reference Material — CPython C Extensions

The four documents to keep open

If you read nothing else, read these. Everything in the course is an elaboration of them.

Python/C API — Introduction	The object model, reference ownership, the error convention. Short, dense, and authoritative. Read it twice.
Extending Python with C or C++	The official tutorial. The fastest way to see the whole shape of a module at once.
Isolating Extension Modules	Per-module state, heap types, subinterpreters. The single most valuable how-to for modern extension design, and the one that most third-party code has not caught up with.
C API Extension Support for Free Threading	The complete checklist for the GIL-free build. Short enough to read in one sitting.

Python/C API — Introduction. Objects, types, reference counts; the conventions everything else assumes.
Common Object Structures. PyObject, PyVarObject, and the access macros.
CPython Include/object.h. Ground truth, and shorter than you expect.
PEP 683 — Immortal Objects. Why refcounts on None stopped meaning anything.
PEP 353 — Using ssize_t as the index type. Why Py_ssize_t is signed.

C API — Reference Counts. Ownership, stealing, and the canonical goto error example.
C API — Reference Counting. Exact semantics of every macro.
Python Extension Patterns — Reference Counts. Paul Ross. Unusually good on failure modes and on detecting them.
PyDict_GetItemRef and PyList_GetItemRef. The strong-reference replacements to prefer in new code.

Defining Extension Types: Tutorial. Builds a type in four stages; the best starting point.
Type Object Structures. The exhaustive slot reference, including inheritance rules.
Type Objects. PyType_Spec, PyType_Slot, PyType_FromModuleAndSpec.
Defining Extension Types: Assorted Topics. Attributes, comparisons, weak references.
PEP 384 — Defining a Stable ABI. Where PyType_Spec came from.
Descriptor HowTo Guide. What PyMemberDef and PyGetSetDef actually produce.

Supporting Cyclic Garbage Collection. The contract and the required deallocation order.
Devguide — Garbage Collector Design. The clearest explanation of the reference-subtraction algorithm and generations.
PEP 442 — Safe Object Finalization. Why tp_finalize exists.
The gc module. get_referents is a free test for tp_traverse.

C API — Exception Handling. Every function, with exact semantics.
Python Extension Patterns — Exceptions. Custom exception types and library-error translation.
sys.unraisablehook. Where PyErr_FormatUnraisable ends up.
PEP 654 — Exception Groups and PEP 678 — Exception Notes, for wrappers that aggregate failures.

Parsing Arguments and Building Values. The complete format-unit table; note which units borrow.
Implementing Functions and Methods. PyMethodDef and every METH_ flag.
C API — Call Protocol. Vectorcall and the full set of calling APIs.
PEP 590 — Vectorcall. Why METH_FASTCALL is faster.
Argument Clinic How-To. Generated fast keyword parsers and real signatures.

C API — Module Objects. PyModuleDef, every slot, the PyModule_Add* family.
Isolating Extension Modules. Read twice.
PEP 489 — Multi-phase initialization.
PEP 573 — Module State Access from C Extension Methods. The defining_class mechanism.
PEP 793 — PyModExport. The Python 3.15 entry point; PyInit_* becomes soft-deprecated.

setuptools — Building Extension Modules.
C API Stability. The authoritative statement on the Limited API and abi3.
Packaging Guide — Binary Extensions.
cibuildwheel. Wheels for every platform and interpreter, free-threaded included.
pypackaging-native. Clear-eyed survey of why native packaging is hard.
meson-python and scikit-build-core. Alternative PEP 517 backends for larger native builds.

Thread State and the GIL. The precise contract; note the attached/detached terminology.
Synchronization Primitives. PyMutex, PyEvent, critical sections.
PEP 684 — A Per-Interpreter GIL and PEP 734 — Multiple Interpreters in the Stdlib.
David Beazley — Understanding the Python GIL (PDF). Dated specifics, still the clearest account of contention behaviour.
Victor Stinner's blog. Current, deep write-ups on thread state, finalization and internals.

C API — Buffer Protocol. Every field and flag, and the exporter/consumer contract.
PEP 3118 — Revising the buffer protocol. Why strides and suboffsets exist.
memoryview. The protocol, explorable from the REPL.
NumPy C-API: Array API, if your extension is NumPy-specific.
DLPack. Zero-copy exchange including device memory.

C API — Capsules and Providing a C API for an Extension Module.
C API — Unicode Objects. UTF-8 access and the filesystem-encoding converters.
CPython Modules/_sqlite/. The best-documented real wrapper: heap types, module state, error translation, callbacks.
CPython Modules/zlibmodule.c. The canonical example of releasing the interpreter around library work.
Python Extension Patterns. Long-form patterns, including resource management and thread safety.

Cython, nanobind, pybind11, cffi, PyO3, HPy.
pythoncapi-compat. Backports modern C API functions to older Pythons; removes most version-conditional code.
discuss.python.org — C API. Where the API's direction is set before it reaches the docs.
CPython Developer's Guide. Building CPython, debug builds, internals docs.

CPython Internals, Anthony Shaw. A guided tour of the source tree. Useful orientation; check details against current documentation, since the interpreter has changed substantially since publication.
Python Extension Patterns, Paul Ross. Free online. The closest thing to a book specifically about writing C extensions correctly.
CPython InternalDocs/. Short, current, written by the people doing the work. Underused.