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.
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:
- :file:`Lib/{<module>}.py`
- :file:`Modules/_{<module>}.c` (if there's also a C accelerator module)
- :file:`Lib/test/test_{<module>}.py`
- :file:`Doc/library/{<module>}.rst`
For extension-only modules, the typical layout is:
- :file:`Modules/{<module>}module.c`
- :file:`Lib/test/test_{<module>}.py`
- :file:`Doc/library/{<module>}.rst`
For builtin types, the typical layout is:
- :file:`Objects/{<builtin>}object.c`
- :file:`Lib/test/test_{<builtin>}.py`
- :file:`Doc/library/stdtypes.rst`
For builtin functions, the typical layout is:
Some exceptions:
- builtin type
intis at :file:`Objects/longobject.c` - builtin type
stris at :file:`Objects/unicodeobject.c` - builtin module
sysis at :file:`Python/sysmodule.c` - builtin module
marshalis at :file:`Python/marshal.c` - Windows-only module
winregis at :file:`PC/winreg.c`
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:
| 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 |
| 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 |