From 34eed9be90960da6375edddb41a860f26a52fabe Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 2 Dec 2025 21:06:20 +0000 Subject: [PATCH 1/2] Remove dead internals pages --- conf.py | 12 ++++++++---- developer-workflow/c-api.rst | 2 +- index.rst | 7 ++----- internals/exploring.rst => internals.rst | 22 +++++++++++++++++++--- internals/compiler.rst | 10 ---------- internals/garbage-collector.rst | 12 ------------ internals/index.rst | 20 -------------------- internals/interpreter.rst | 8 -------- internals/parser.rst | 10 ---------- 9 files changed, 30 insertions(+), 73 deletions(-) rename internals/exploring.rst => internals.rst (89%) delete mode 100644 internals/compiler.rst delete mode 100644 internals/garbage-collector.rst delete mode 100644 internals/index.rst delete mode 100644 internals/interpreter.rst delete mode 100644 internals/parser.rst diff --git a/conf.py b/conf.py index 0f6a820d88..02f9c74771 100644 --- a/conf.py +++ b/conf.py @@ -149,10 +149,14 @@ "pullrequest.rst": "getting-started/pull-request-lifecycle.rst", "setup.rst": "getting-started/setup-building.rst", # CPython Internals - "compiler.rst": "internals/compiler.rst", - "exploring.rst": "internals/exploring.rst", - "garbage_collector.rst": "internals/garbage-collector.rst", - "parser.rst": "internals/parser.rst", + "compiler.rst": "internals.rst", + "exploring.rst": "internals.rst", + "garbage_collector.rst": "internals.rst", + "parser.rst": "internals.rst", + "internals/compiler.rst": "internals.rst", + "internals/exploring.rst": "internals.rst", + "internals/garbage_collector.rst": "internals.rst", + "internals/parser.rst": "internals.rst", # Testing and Buildbots "buildbots.rst": "testing/buildbots.rst", "coverage.rst": "testing/coverage.rst", diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 90c1d12e4e..67c9814079 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -387,7 +387,7 @@ Guidelines for adding to the Limited API details involve: - The GIL - - :ref:`Garbage collection ` + - Garbage collection - Memory layout of PyObject, lists/tuples and other structures If following these guidelines would hurt performance, add a fast function diff --git a/index.rst b/index.rst index e19bb88263..cc91e50882 100644 --- a/index.rst +++ b/index.rst @@ -267,11 +267,8 @@ Additional resources * Anyone can clone the sources for this guide. See :ref:`devguide`. * Help with ... - * :ref:`exploring` + * :ref:`internals` * :ref:`grammar` - * :ref:`parser` - * :ref:`compiler` - * :ref:`garbage_collector` * Tool support @@ -317,7 +314,7 @@ Full table of contents testing/index development-tools/index core-team/index - internals/index + internals versions contrib/index diff --git a/internals/exploring.rst b/internals.rst similarity index 89% rename from internals/exploring.rst rename to internals.rst index 0ae8337e8c..42c5533e33 100644 --- a/internals/exploring.rst +++ b/internals.rst @@ -1,6 +1,14 @@ -.. _exploring: +.. _internals: =================== +CPython's internals +=================== + +This guide describes the basics of CPython’s internals. +It explains the layout of CPython’s source code. + +.. _exploring: + CPython source code =================== @@ -9,7 +17,7 @@ a summary of file locations for modules and built-ins. Source code layout -================== +------------------ For a Python :term:`module`, the typical layout is: @@ -46,7 +54,7 @@ Some exceptions to these layouts are: Additional references -===================== +--------------------- The CPython code base is constantly changing and evolving. Here's a sample of references about CPython's architecture aimed at @@ -92,3 +100,11 @@ building your understanding of CPython internals and its evolution: .. _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: https://www.youtube.com/playlist?list=PLzV58Zm8FuBL6OAv1Yu6AwXZrnsFbbR0S + + +CPython InternalDocs +==================== + +For more detailed and up-to-date documentation on CPython's internals, +please refer to the `InternalDocs folder `_ +in the CPython repository. diff --git a/internals/compiler.rst b/internals/compiler.rst deleted file mode 100644 index 5b43e1e6dc..0000000000 --- a/internals/compiler.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _compiler: - -=============== -Compiler design -=============== - -.. highlight:: none - -This document is now part of the -`CPython Internals Docs `_. diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst deleted file mode 100644 index acbcedf0e8..0000000000 --- a/internals/garbage-collector.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _garbage-collector: -.. _gc: -.. _garbage_collector: - -======================== -Garbage collector design -======================== - -.. highlight:: none - -This document is now part of the -`CPython Internals Docs `_. diff --git a/internals/index.rst b/internals/index.rst deleted file mode 100644 index 05723f4824..0000000000 --- a/internals/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _internals: - -=================== -CPython's internals -=================== - -This guide describes the basics of CPython's internals. -It explains the layout of CPython's source code. -It also explains how the parser, compiler, and interpreter -work together to run your Python code. -Finally, it covers the garbage collector and how it manages memory. - -.. toctree:: - :maxdepth: 3 - - exploring - parser - compiler - interpreter - garbage-collector diff --git a/internals/interpreter.rst b/internals/interpreter.rst deleted file mode 100644 index a7ae39c120..0000000000 --- a/internals/interpreter.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _interpreter: - -======================== -The bytecode interpreter -======================== - -This document is now part of the -`CPython Internals Docs `_. diff --git a/internals/parser.rst b/internals/parser.rst deleted file mode 100644 index 688ad61e77..0000000000 --- a/internals/parser.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _parser: - -=================== -Guide to the parser -=================== - -.. highlight:: none - -This document is now part of the -`CPython Internals Docs `_. From dd45257d6d015694a195e0a328fb4a0b95d58bae Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 15 Dec 2025 18:51:23 +0000 Subject: [PATCH 2/2] Post-move final page to InternalDocs --- internals.rst | 62 ++------------------------------------------------- 1 file changed, 2 insertions(+), 60 deletions(-) diff --git a/internals.rst b/internals.rst index 42c5533e33..3948d6397c 100644 --- a/internals.rst +++ b/internals.rst @@ -4,58 +4,6 @@ CPython's internals =================== -This guide describes the basics of CPython’s internals. -It explains the layout of CPython’s source code. - -.. _exploring: - -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 :term:`module`, the typical layout is: - -* :file:`Lib/{}.py` -* :file:`Modules/_{}.c` (if there's also a C accelerator module) -* :file:`Lib/test/test_{}.py` -* :file:`Doc/library/{}.rst` - -For an :term:`extension module`, the typical layout is: - -* :file:`Modules/{}module.c` -* :file:`Lib/test/test_{}.py` -* :file:`Doc/library/{}.rst` - -For :ref:`bltin-types`, the typical layout is: - -* :file:`Objects/{}object.c` -* :file:`Lib/test/test_{}.py` -* :cpy-file:`Doc/library/stdtypes.rst` - -For :ref:`built-in-funcs`, the typical layout is: - -* :cpy-file:`Python/bltinmodule.c` -* :cpy-file:`Lib/test/test_builtin.py` -* :cpy-file:`Doc/library/functions.rst` - -Some exceptions to these layouts are: - -* built-in type ``int`` is at :cpy-file:`Objects/longobject.c` -* built-in type ``str`` is at :cpy-file:`Objects/unicodeobject.c` -* built-in module ``sys`` is at :cpy-file:`Python/sysmodule.c` -* built-in module ``marshal`` is at :cpy-file:`Python/marshal.c` -* Windows-only module ``winreg`` is at :cpy-file:`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: @@ -64,6 +12,7 @@ building your understanding of CPython internals and its evolution: :header: "Title", "Brief", "Author", "Version" :widths: 50, 50, 20, 5 + "`CPython's InternalDocs`_", "Docs on CPython internals maintained in the source tree", "", "" "`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 @@ -80,6 +29,7 @@ building your understanding of CPython internals and its evolution: "`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 +.. _CPython's InternalDocs: https://github.com/python/cpython/tree/main/InternalDocs .. _A guide from parser to objects, observed using GDB: https://hackmd.io/s/ByMHBMjFe @@ -100,11 +50,3 @@ building your understanding of CPython internals and its evolution: .. _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: https://www.youtube.com/playlist?list=PLzV58Zm8FuBL6OAv1Yu6AwXZrnsFbbR0S - - -CPython InternalDocs -==================== - -For more detailed and up-to-date documentation on CPython's internals, -please refer to the `InternalDocs folder `_ -in the CPython repository.