diff --git a/InternalDocs/README.md b/InternalDocs/README.md index 2ef6e653ac19d4..68cb3d909cf8f1 100644 --- a/InternalDocs/README.md +++ b/InternalDocs/README.md @@ -11,8 +11,9 @@ The core dev team attempts to keep this documentation up to date. If it is not, please report that through the [issue tracker](https://github.com/python/cpython/issues). +- [Structure of the CPython Repository](repo_structure.md) -Compiling Python Source Code +Compilation --- - [Guide to the parser](parser.md) @@ -42,3 +43,7 @@ Program Execution - [Garbage Collector Design](garbage_collector.md) - [Exception Handling](exception_handling.md) + +--- + +- [External Resources](external_resources.md) diff --git a/InternalDocs/external_resources.md b/InternalDocs/external_resources.md new file mode 100644 index 00000000000000..79592f41cac418 --- /dev/null +++ b/InternalDocs/external_resources.md @@ -0,0 +1,20 @@ + +# External Resources About CPython + +The CPython code base is constantly changing and evolving. +Below are references to external resources about CPython's architecture aimed at +building your understanding of CPython internals and its evolution: + + +| 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 | +| [`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 | diff --git a/InternalDocs/repo_structure.md b/InternalDocs/repo_structure.md new file mode 100644 index 00000000000000..1b686162c292b7 --- /dev/null +++ b/InternalDocs/repo_structure.md @@ -0,0 +1,49 @@ + +# The CPython Repository + +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 +================== + +The core interpreter implementation is in the [`Python/`](../Python) directory. +Some of the files there are generated during the build process, that will be +indicated by a comment at the top of the file. + +For a Python [`module`](https://docs.python.org/3/glossary.html#term-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`](https://docs.python.org/3/glossary.html#term-extension-module), +the typical layout is: + +* `Modules/{}module.c` +* `Lib/test/test_{}.py` +* `Doc/library/{}.rst` + +For [`bltin-types`](https://docs.python.org/3/library/stdtypes.html#bltin-types), +the typical layout is: + +* `Objects/{}object.c` +* `Lib/test/test_{}.py` +* [`Doc/library/stdtypes.rst`](../Doc/library/stdtypes.rst) + +For [`built-in-funcs`](https://docs.python.org/3/library/functions.html#built-in-funcs), +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)