.. _exploring:

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.


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:

* :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:

* :file:`Python/bltinmodule.c`
* :file:`Lib/test/test_builtin.py`
* :file:`Doc/library/functions.rst`

Some exceptions:

* builtin type ``int`` is at :file:`Objects/longobject.c`
* builtin type ``str`` is at :file:`Objects/unicodeobject.c`
* builtin module ``sys`` is at :file:`Python/sysmodule.c`
* builtin module ``marshal`` is at :file:`Python/marshal.c`
* Windows-only module ``winreg`` is at :file:`PC/winreg.c`


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:


.. csv-table:: **Current references**
   :header: "Title", "Brief", "Author", "Version"
   :widths: 50, 50, 20, 5

    "`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

.. csv-table:: **Historical references**
   :header: "Title", "Brief", "Author", "Version"
   :widths: 50, 50, 20, 5

    "`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


.. _A guide from parser to objects, observed using GDB: https://hackmd.io/s/ByMHBMjFe

.. _Green Tree Snakes: https://greentreesnakes.readthedocs.io/en/latest/

.. _Yet another guided tour of CPython: https://paper.dropbox.com/doc/Yet-another-guided-tour-of-CPython-XY7KgFGn88zMNivGJ4Jzv

.. _Python Asynchronous I/O Walkthrough: http://pgbovine.net/python-async-io-walkthrough.htm

.. _Coding Patterns for Python Extensions: https://pythonextensionpatterns.readthedocs.io/en/latest/

.. _Your Guide to the CPython Source Code: https://realpython.com/cpython-source-code-guide/

.. _Python's Innards Series: https://tech.blog.aknin.name/category/my-projects/pythons-innards/

.. _Eli Bendersky's Python Internals: https://eli.thegreenplace.net/tag/python-internals

.. _A guide from parser to objects, observed using Eclipse: https://docs.google.com/document/d/1nzNN1jeNCC_bg1LADCvtTuGKvcyMskV1w8Ad2iLlwoI/

.. _CPython internals\: A ten-hour codewalk through the Python interpreter source code: http://pgbovine.net/cpython-internals.htm