From 991d6e11ca27643e7688e1be1c8894d0b3c5f61e Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 3 Dec 2025 20:30:29 +0000 Subject: [PATCH 1/2] Add structure.md doc Co-Authored-By: Paul Ross Co-Authored-By: Carol Willing Co-Authored-By: Hugo van Kemenade Co-Authored-By: Ezio Melotti Co-Authored-By: Adam Turner <9087854+aa-turner@users.noreply.github.com> Co-Authored-By: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- InternalDocs/README.md | 5 +++ InternalDocs/structure.md | 69 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 InternalDocs/structure.md diff --git a/InternalDocs/README.md b/InternalDocs/README.md index a6e2df5ae4a9c3..e9cf52b56af701 100644 --- a/InternalDocs/README.md +++ b/InternalDocs/README.md @@ -11,6 +11,11 @@ it is not, please report that through the [issue tracker](https://github.com/python/cpython/issues). +General Resources +--- + +- [Source Code Structure](structure.md) + Compiling Python Source Code --- diff --git a/InternalDocs/structure.md b/InternalDocs/structure.md new file mode 100644 index 00000000000000..02a4e710a3c57e --- /dev/null +++ b/InternalDocs/structure.md @@ -0,0 +1,69 @@ +# CPython source code + +This section gives an overview of CPython's code structure and provides +a summary of file locations for modules and built-ins. + + +## Source code layout + +For a Python module, the typical layout is: + +* `Lib/.py` +* `Modules/_.c` (if there's also a C accelerator module) +* `Lib/test/test_.py` +* `Doc/library/.rst` + +For an extension module, the typical layout is: + +* `Modules/module.c` +* `Lib/test/test_.py` +* `Doc/library/.rst` + +For builtin types, the typical layout is: + +* `Objects/object.c` +* `Lib/test/test_.py` +* [`Doc/library/stdtypes.rst`](../Doc/library/stdtypes.rst) + +For builtin functions, the typical layout is: + +* [`Python/bltinmodule.c`](../Python/bltinmodule.c) +* [`Lib/test/test_builtin.py`](../Lib/test/test_builtin.py) +* [`Doc/library/functions.rst`](../Doc/library/functions.rst) + +Some exceptions to these layouts are: + +* built-in type `int` is at [`Objects/longobject.c`](../Objects/longobject.c) +* built-in type `str` is at [`Objects/unicodeobject.c`](../Objects/unicodeobject.c) +* built-in module `sys` is at [`Python/sysmodule.c`](../Python/sysmodule.c) +* built-in module `marshal` is at [`Python/marshal.c`](../Python/marshal.c) +* Windows-only module `winreg` is at [`PC/winreg.c`](../PC/winreg.c) + + +## Additional references + +The CPython code base is constantly changing and evolving. +Here's a sample of references about CPython's architecture aimed at +building your understanding of CPython internals and its evolution: + + +### Current references + +| Title | Brief | Author | Version | +|------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|------------------|---------| +| [A guide from parser to objects, observed using GDB](https://hackmd.io/s/ByMHBMjFe) | Code walk from Parser, AST, Sym Table and Objects | Louie Lu | 3.7.a0 | +| [Green Tree Snakes](https://greentreesnakes.readthedocs.io/en/latest/) | The missing Python AST docs | Thomas Kluyver | 3.6 | +| [Yet another guided tour of CPython](https://paper.dropbox.com/doc/Yet-another-guided-tour-of-CPython-XY7KgFGn88zMNivGJ4Jzv) | A guide for how CPython REPL works | Guido van Rossum | 3.5 | +| [Python Asynchronous I/O Walkthrough](https://www.youtube.com/playlist?list=PLpEcQSRWP2IjVRlTUptdD05kG-UkJynQT) | How CPython async I/O, generator and coroutine works | Philip Guo | 3.5 | +| [Coding Patterns for Python Extensions](https://pythonextensionpatterns.readthedocs.io/en/latest/) | Reliable patterns of coding Python Extensions in C | Paul Ross | 3.9+ | +| [Your Guide to the CPython Source Code](https://realpython.com/cpython-source-code-guide/) | Your Guide to the CPython Source Code | Anthony Shaw | 3.8 | + + +### Historical references + +| Title | Brief | Author | Version | +|---------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|-----------------|---------| +| [Python's Innards Series](https://tech.blog.aknin.name/category/my-projects/pythons-innards/) | ceval, objects, pystate and miscellaneous topics | Yaniv Aknin | 3.1 | +| [Eli Bendersky's Python Internals](https://eli.thegreenplace.net/tag/python-internals) | Objects, Symbol tables and miscellaneous topics | Eli Bendersky | 3.x | +| [A guide from parser to objects, observed using Eclipse](https://docs.google.com/document/d/1nzNN1jeNCC_bg1LADCvtTuGKvcyMskV1w8Ad2iLlwoI/) | 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](https://www.youtube.com/playlist?list=PLzV58Zm8FuBL6OAv1Yu6AwXZrnsFbbR0S) | Code walk from source code to generators | Philip Guo | 2.7.8 | \ No newline at end of file From 48db5d6c75aa05caf7a60383e1dd574f9644ed5f Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 4 Dec 2025 20:44:17 +0000 Subject: [PATCH 2/2] Remove lists of links --- InternalDocs/structure.md | 29 ----------------------------- 1 file changed, 29 deletions(-) diff --git a/InternalDocs/structure.md b/InternalDocs/structure.md index 02a4e710a3c57e..75c8476aa0ad98 100644 --- a/InternalDocs/structure.md +++ b/InternalDocs/structure.md @@ -38,32 +38,3 @@ Some exceptions to these layouts are: * built-in module `sys` is at [`Python/sysmodule.c`](../Python/sysmodule.c) * built-in module `marshal` is at [`Python/marshal.c`](../Python/marshal.c) * Windows-only module `winreg` is at [`PC/winreg.c`](../PC/winreg.c) - - -## Additional references - -The CPython code base is constantly changing and evolving. -Here's a sample of references about CPython's architecture aimed at -building your understanding of CPython internals and its evolution: - - -### Current references - -| Title | Brief | Author | Version | -|------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|------------------|---------| -| [A guide from parser to objects, observed using GDB](https://hackmd.io/s/ByMHBMjFe) | Code walk from Parser, AST, Sym Table and Objects | Louie Lu | 3.7.a0 | -| [Green Tree Snakes](https://greentreesnakes.readthedocs.io/en/latest/) | The missing Python AST docs | Thomas Kluyver | 3.6 | -| [Yet another guided tour of CPython](https://paper.dropbox.com/doc/Yet-another-guided-tour-of-CPython-XY7KgFGn88zMNivGJ4Jzv) | A guide for how CPython REPL works | Guido van Rossum | 3.5 | -| [Python Asynchronous I/O Walkthrough](https://www.youtube.com/playlist?list=PLpEcQSRWP2IjVRlTUptdD05kG-UkJynQT) | How CPython async I/O, generator and coroutine works | Philip Guo | 3.5 | -| [Coding Patterns for Python Extensions](https://pythonextensionpatterns.readthedocs.io/en/latest/) | Reliable patterns of coding Python Extensions in C | Paul Ross | 3.9+ | -| [Your Guide to the CPython Source Code](https://realpython.com/cpython-source-code-guide/) | Your Guide to the CPython Source Code | Anthony Shaw | 3.8 | - - -### Historical references - -| Title | Brief | Author | Version | -|---------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|-----------------|---------| -| [Python's Innards Series](https://tech.blog.aknin.name/category/my-projects/pythons-innards/) | ceval, objects, pystate and miscellaneous topics | Yaniv Aknin | 3.1 | -| [Eli Bendersky's Python Internals](https://eli.thegreenplace.net/tag/python-internals) | Objects, Symbol tables and miscellaneous topics | Eli Bendersky | 3.x | -| [A guide from parser to objects, observed using Eclipse](https://docs.google.com/document/d/1nzNN1jeNCC_bg1LADCvtTuGKvcyMskV1w8Ad2iLlwoI/) | 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](https://www.youtube.com/playlist?list=PLzV58Zm8FuBL6OAv1Yu6AwXZrnsFbbR0S) | Code walk from source code to generators | Philip Guo | 2.7.8 | \ No newline at end of file