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: