24. Exploring CPython’s Internals

This is a quick guide for people who are interested in learning more about CPython’s internals. It provides a summary of the source code structure and contains references to resources providing a more in-depth view.

24.1. CPython Source Code Layout

This guide gives an overview of CPython’s code structure. It serves as a summary of file locations for modules and builtins.

  • Lib/<module>.py
  • Modules/_<module>module.c (if there’s also a C accelerator module)
  • Lib/test/test_<module>.py
  • Doc/library/<module>.rst

For extension-only modules, the typical layout is:

  • Modules/<module>module.c
  • Lib/test/test_<module>.py
  • Doc/library/<module>.rst

For builtin types, the typical layout is:

  • Objects/<builtin>object.c
  • Lib/test/test_<builtin>.py
  • Doc/library/stdtypes.rst

For builtin functions, the typical layout is:

  • Python/bltinmodule.c
  • Lib/test/test_<builtin>.py
  • Doc/library/functions.rst

Some Exceptions:

  • builtin type int is at Objects/longobject.c
  • builtin type str is at Objects/unicodeobject.c

24.2. Additional References

For over 20 years the CPython code base has been changing and evolving. Here’s a sample of resources about the architecture of CPython aimed at building your understanding of both the 2.x and 3.x versions of CPython:

Current references
Title Brief Author Version
A guide from parser to objects, observed using GDB Code walk from Parser, AST, Sym Table and Objects Louie Lu 3.7.a0
Yet another guided tour of CPython A guide for how CPython REPL works Guido van Rossum 3.5
Python Asynchronous I/O Walkthrough How CPython async I/O, generator and coroutine works Philip Guo 3.5
Historical references
Title Brief Author Version
Python’s Innards Series ceval, objects, pystate and miscellaneous topics Yaniv Aknin 3.1
Eli Bendersky’s Python Internals Objects, Symbol tables and miscellaneous topics Eli Bendersky 3.x
A guide from parser to objects, observed using Eclipse Code walk from Parser, AST, Sym Table and Objects Prashanth Raghu 2.7.12
CPython internals: A ten-hour codewalk through the Python interpreter source code Code walk from source code to generators Philip Guo 2.7.8