23. 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.

23.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.

For Python modules, the typical layout is:

  • Lib/<module>.py
  • Modules/_<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
  • builtin module sys is at Python/sysmodule.c
  • builtin module marshal is at Python/marshal.c
  • Windows-only module winreg is at PC/winreg.c

23.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
Green Tree Snakes The missing Python AST docs Thomas Kluyver 3.6
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
Coding Patterns for Python Extensions Reliable patterns of coding Python Extensions in C Paul Ross 3.4
Your Guide to the CPython Source Code Your Guide to the CPython Source Code Anthony Shaw 3.8
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