From 15c151775cdc18f662e92e5ae3b92f93a2fca00e Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sun, 13 Nov 2022 21:56:08 -0700 Subject: [PATCH 1/2] Use :cpy-file: throughout the Devguide. --- core-developers/experts.rst | 2 +- developer-workflow/c-api.rst | 4 +- developer-workflow/grammar.rst | 49 +++++------ documentation/start-documenting.rst | 14 ++-- getting-started/git-boot-camp.rst | 2 +- internals/compiler.rst | 123 ++++++++++++++-------------- internals/exploring.rst | 18 ++-- 7 files changed, 109 insertions(+), 103 deletions(-) diff --git a/core-developers/experts.rst b/core-developers/experts.rst index 0aa8104de1..95f9e922e1 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -17,7 +17,7 @@ while any other issues can and should be decided by any committer. Developers can choose to follow labels, so if a label that they are following is added to an issue or pull request, they will be notified -automatically. The :file:`CODEOWNERS` file is also used to indicate +automatically. The :cpy-file:`CODEOWNERS` file is also used to indicate maintainers that will be automatically added as reviewers to pull requests. Unless a name is followed by a '*', you should never assign an issue to diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 5564bdc9c4..a85ad34428 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -101,12 +101,12 @@ C API Tests Tests for the public C API live in the ``_testcapi`` module. Functions named ``test_*`` are used as tests directly. Tests that need Python code (or are just easier to partially write in Python) -live in ``Lib/test``, mainly in :file:`Lib/test/test_capi.py`. +live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi.py`. Due to its size, the ``_testcapi`` module is defined in several source files. To add a new set of tests (or extract a set out of the monolithic -:file:`Modules/_testcapimodule.c`): +:cpy-file:`Modules/_testcapimodule.c`): - Create a C file named ``Modules/_testcapi/yourfeature.c`` diff --git a/developer-workflow/grammar.rst b/developer-workflow/grammar.rst index 7ff1ed12ad..7d6b40993f 100644 --- a/developer-workflow/grammar.rst +++ b/developer-workflow/grammar.rst @@ -8,7 +8,7 @@ Abstract ======== There's more to changing Python's grammar than editing -:file:`Grammar/python.gram`. Here's a checklist. +:cpy-file:`Grammar/python.gram`. Here's a checklist. .. note:: These instructions are for Python 3.9 and beyond. Earlier @@ -25,42 +25,45 @@ Checklist Note: sometimes things mysteriously don't work. Before giving up, try ``make clean``. -* :file:`Grammar/python.gram`: The grammar, with actions that build AST nodes. After changing - it, run ``make regen-pegen`` (or ``build.bat --regen`` on Windows), to - regenerate :file:`Parser/parser.c`. +* :cpy-file:`Grammar/python.gram`: The grammar, with actions that build AST nodes. + After changing it, run ``make regen-pegen`` (or ``build.bat --regen`` on Windows), + to regenerate :cpy-file:`Parser/parser.c`. (This runs Python's parser generator, ``Tools/peg_generator``). -* :file:`Grammar/Tokens` is a place for adding new token types. After - changing it, run ``make regen-token`` to regenerate :file:`Include/token.h`, - :file:`Parser/token.c`, :file:`Lib/token.py` and - :file:`Doc/library/token-list.inc`. If you change both ``python.gram`` and ``Tokens``, - run ``make regen-token`` before ``make regen-pegen``. On Windows, - ``build.bat --regen`` will regenerate both at the same time. +* :cpy-file:`Grammar/Tokens` is a place for adding new token types. After + changing it, run ``make regen-token`` to regenerate :cpy-file:`Include/token.h`, + :cpy-file:`Parser/token.c`, :cpy-file:`Lib/token.py` and + :cpy-file:`Doc/library/token-list.inc`. If you change both ``python.gram`` + and ``Tokens``, run ``make regen-token`` before ``make regen-pegen``. + On Windows, ``build.bat --regen`` will regenerate both at the same time. -* :file:`Parser/Python.asdl` may need changes to match the grammar. Then run ``make - regen-ast`` to regenerate :file:`Include/Python-ast.h` and :file:`Python/Python-ast.c`. +* :cpy-file:`Parser/Python.asdl` may need changes to match the grammar. + Then run ``make regen-ast`` to regenerate :cpy-file:`Include/Python-ast.h` + and :cpy-file:`Python/Python-ast.c`. -* :file:`Parser/tokenizer.c` contains the tokenization code. This is where you would - add a new type of comment or string literal, for example. +* :cpy-file:`Parser/tokenizer.c` contains the tokenization code. + This is where you would add a new type of comment or string literal, for example. -* :file:`Python/ast.c` will need changes to validate AST objects involved with the - grammar change. +* :cpy-file:`Python/ast.c` will need changes to validate AST objects + involved with the grammar change. -* :file:`Python/ast_unparse.c` will need changes to unparse AST objects involved with the - grammar change ("unparsing" is used to turn annotations into strings per :pep:`563`). +* :cpy-file:`Python/ast_unparse.c` will need changes to unparse AST + involved with the grammar change ("unparsing" is used to turn annotations + into strings per :pep:`563`). * The :ref:`compiler` has its own page. -* ``_Unparser`` in the :file:`Lib/ast.py` file may need changes to accommodate - any modifications in the AST nodes. +* ``_Unparser`` in the :cpy-file:`Lib/ast.py` file may need changes + to accommodate any modifications in the AST nodes. -* :file:`Doc/library/ast.rst` may need to be updated to reflect changes to AST nodes. +* :cpy-file:`Doc/library/ast.rst` may need to be updated to reflect changes + to AST nodes. * Add some usage of your new syntax to ``test_grammar.py``. * Certain changes may require tweaks to the library module :mod:`pyclbr`. -* :file:`Lib/tokenize.py` needs changes to match changes to the tokenizer. +* :cpy-file:`Lib/tokenize.py` needs changes to match changes to the tokenizer. * Documentation must be written! Specifically, one or more of the pages in - :file:`Doc/reference/` will need to be updated. + :cpy-file:`Doc/reference/` will need to be updated. diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 8a0db24045..175c73c0a5 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -101,11 +101,11 @@ You can also use ``make help`` to see a list of targets supported by you submit a :ref:`pull request `, so you should make sure that it runs without errors. -**On Windows**, a :file:`make.bat` batchfile tries to emulate :command:`make` -as closely as possible, but the venv target is not implemented, so you will -probably want to make sure you are working in a virtual environment before -proceeding, otherwise all dependencies will be automatically installed on your -system. +**On Windows**, the :cpy-file:`Doc/make.bat` batchfile tries to emulate +:command:`make` as closely as possible, but the venv target is not implemented, +so you will probably want to make sure you are working in a virtual environment +before proceeding, otherwise all dependencies will be automatically installed +on your system. When ready, run the following from the root of your :ref:`repository clone ` to build the output as HTML:: @@ -114,9 +114,9 @@ When ready, run the following from the root of your :ref:`repository clone make html You can also use ``make help`` to see a list of targets supported by -:file:`make.bat`. +:cpy-file:`Doc/make.bat`. -See also :file:`Doc/README.rst` for more information. +See also :cpy-file:`Doc/README.rst` for more information. Using sphinx-build ------------------ diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index f5854da562..130b9addfa 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -271,7 +271,7 @@ Exclude generated files from diff by default:: git config diff.generated.binary true The ``generated`` `attribute `_ is -defined in :file:`.gitattributes`, found in the repository root. +defined in :cpy-file:`.gitattributes`, found in the repository root. .. _push-changes: diff --git a/internals/compiler.rst b/internals/compiler.rst index 0e31e1be47..8ed57b9df6 100644 --- a/internals/compiler.rst +++ b/internals/compiler.rst @@ -11,10 +11,11 @@ Abstract In CPython, the compilation from source code to bytecode involves several steps: -1. Tokenize the source code (:file:`Parser/tokenizer.c`) -2. Parse the stream of tokens into an Abstract Syntax Tree (:file:`Parser/parser.c`) -3. Transform AST into a Control Flow Graph (:file:`Python/compile.c`) -4. Emit bytecode based on the Control Flow Graph (:file:`Python/compile.c`) +1. Tokenize the source code (:cpy-file:`Parser/tokenizer.c`) +2. Parse the stream of tokens into an Abstract Syntax Tree + (:cpy-file:`Parser/parser.c`) +3. Transform AST into a Control Flow Graph (:cpy-file:`Python/compile.c`) +4. Emit bytecode based on the Control Flow Graph (:cpy-file:`Python/compile.c`) The purpose of this document is to outline how these steps of the process work. @@ -32,9 +33,9 @@ unusual design (since its input is a stream of tokens rather than a stream of characters as is more common with PEG parsers). The grammar file for Python can be found in -:file:`Grammar/python.gram`. The definitions for literal tokens -(such as ``:``, numbers, etc.) can be found in :file:`Grammar/Tokens`. -Various C files, including :file:`Parser/parser.c` are generated from +:cpy-file:`Grammar/python.gram`. The definitions for literal tokens +(such as ``:``, numbers, etc.) can be found in :cpy-file:`Grammar/Tokens`. +Various C files, including :cpy-file:`Parser/parser.c` are generated from these (see :ref:`grammar`). @@ -55,7 +56,7 @@ specification of the AST nodes is specified using the Zephyr Abstract Syntax Definition Language (ASDL) [Wang97]_. The definition of the AST nodes for Python is found in the file -:file:`Parser/Python.asdl`. +:cpy-file:`Parser/Python.asdl`. Each AST node (representing statements, expressions, and several specialized types, like list comprehensions and exception handlers) is @@ -142,7 +143,7 @@ In general, unless you are working on the critical core of the compiler, memory management can be completely ignored. But if you are working at either the very beginning of the compiler or the end, you need to care about how the arena works. All code relating to the arena is in either -:file:`Include/Internal/pycore_pyarena.h` or :file:`Python/pyarena.c`. +:cpy-file:`Include/Internal/pycore_pyarena.h` or :cpy-file:`Python/pyarena.c`. ``PyArena_New()`` will create a new arena. The returned ``PyArena`` structure will store pointers to all memory given to it. This does the bookkeeping of @@ -166,15 +167,16 @@ Source Code to AST The AST is generated from source code using the function ``_PyParser_ASTFromString()`` or ``_PyParser_ASTFromFile()`` -(from :file:`Parser/peg_api.c`) depending on the input type. +(from :cpy-file:`Parser/peg_api.c`) depending on the input type. -After some checks, a helper function in :file:`Parser/parser.c` begins applying +After some checks, a helper function in :cpy-file:`Parser/parser.c` begins applying production rules on the source code it receives; converting source code to tokens and matching these tokens recursively to their corresponding rule. The rule's corresponding rule function is called on every match. These rule functions follow the format :samp:`xx_rule`. Where *xx* is the grammar rule that the function handles and is automatically derived from -:file:`Grammar/python.gram` by :file:`Tools/peg_generator/pegen/c_generator.py`. +:cpy-file:`Grammar/python.gram` +:cpy-file:`Tools/peg_generator/pegen/c_generator.py`. Each rule function in turn creates an AST node as it goes along. It does this by allocating all the new nodes it needs, calling the proper AST node creation @@ -185,9 +187,9 @@ there are no more rules, an error is set and the parsing ends. The AST node creation helper functions have the name :samp:`_PyAST_{xx}` where *xx* is the AST node that the function creates. These are defined by the -ASDL grammar and contained in :file:`Python/Python-ast.c` (which is generated by -:file:`Parser/asdl_c.py` from :file:`Parser/Python.asdl`). This all leads to a -sequence of AST nodes stored in ``asdl_seq`` structs. +ASDL grammar and contained in :cpy-file:`Python/Python-ast.c` (which is +generated by :cpy-file:`Parser/asdl_c.py` from :cpy-file:`Parser/Python.asdl`). +This all leads to a sequence of AST nodes stored in ``asdl_seq`` structs. To demonstrate everything explained so far, here's the rule function responsible for a simple named import statement such as @@ -240,8 +242,8 @@ manner stated in the previous paragraphs. There are macros for creating and using ``asdl_xx_seq *`` types, where *xx* is a type of the ASDL sequence. Three main types are defined manually -- ``generic``, ``identifier`` and ``int``. These types are found in -:file:`Python/asdl.c` and its corresponding header file -:file:`Include/Internal/pycore_asdl.h`. Functions and macros +:cpy-file:`Python/asdl.c` and its corresponding header file +:cpy-file:`Include/Internal/pycore_asdl.h`. Functions and macros for creating ``asdl_xx_seq *`` types are as follows: ``_Py_asdl_generic_seq_new(Py_ssize_t, PyArena *)`` @@ -252,9 +254,9 @@ for creating ``asdl_xx_seq *`` types are as follows: Allocate memory for an ``asdl_int_seq`` of the specified length In addition to the three types mentioned above, some ASDL sequence types are -automatically generated by :file:`Parser/asdl_c.py` and found in -:file:`Include/Internal/pycore_ast.h`. Macros for using both manually defined -and automatically generated ASDL sequence types are as follows: +automatically generated by :cpy-file:`Parser/asdl_c.py` and found in +:cpy-file:`Include/Internal/pycore_ast.h`. Macros for using both manually +defined and automatically generated ASDL sequence types are as follows: ``asdl_seq_GET(asdl_xx_seq *, int)`` Get item held at a specific position in an ``asdl_xx_seq`` @@ -348,11 +350,12 @@ global). With that done, the second pass essentially flattens the CFG into a list and calculates jump offsets for final output of bytecode. The conversion process is initiated by a call to the function -``_PyAST_Compile()`` in :file:`Python/compile.c`. This function does both the -conversion of the AST to a CFG and outputting final bytecode from the CFG. +``_PyAST_Compile()`` in :cpy-file:`Python/compile.c`. This function does both +the conversion of the AST to a CFG and outputting final bytecode from the CFG. The AST to CFG step is handled mostly by two functions called by -``_PyAST_Compile()``; ``_PySymtable_Build()`` and ``compiler_mod()``. The former -is in :file:`Python/symtable.c` while the latter is in :file:`Python/compile.c`. +``_PyAST_Compile()``; ``_PySymtable_Build()`` and ``compiler_mod()``. +The former is in :cpy-file:`Python/symtable.c` while the latter is +:cpy-file:`Python/compile.c`. ``_PySymtable_Build()`` begins by entering the starting code block for the AST (passed-in) and then calling the proper :samp:`symtable_visit_{xx}` function @@ -362,7 +365,7 @@ as blocks are entered and exited using ``symtable_enter_block()`` and ``symtable_exit_block()``, respectively. Once the symbol table is created, it is time for CFG creation, whose -code is in :file:`Python/compile.c`. This is handled by several functions +code is in :cpy-file:`Python/compile.c`. This is handled by several functions that break the task down by various AST node types. The functions are all named :samp:`compiler_visit_{xx}` where *xx* is the name of the node type (such as ``stmt``, ``expr``, etc.). Each function receives a ``struct compiler *`` @@ -458,24 +461,24 @@ bytecode step of the compiler. Several pieces of code throughout Python depend on having correct information about what bytecode exists. First, you must choose a name and a unique identifier number. The official -list of bytecode can be found in :file:`Lib/opcode.py`. If the opcode is to +list of bytecode can be found in :cpy-file:`Lib/opcode.py`. If the opcode is to take an argument, it must be given a unique number greater than that assigned to -``HAVE_ARGUMENT`` (as found in :file:`Lib/opcode.py`). +``HAVE_ARGUMENT`` (as found in :cpy-file:`Lib/opcode.py`). -Once the name/number pair has been chosen and entered in :file:`Lib/opcode.py`, -you must also enter it into :file:`Doc/library/dis.rst`, and regenerate -:file:`Include/opcode.h` and :file:`Python/opcode_targets.h` by running +Once the name/number pair has been chosen and entered in :cpy-file:`Lib/opcode.py`, +you must also enter it into :cpy-file:`Doc/library/dis.rst`, and regenerate +:cpy-file:`Include/opcode.h` and :cpy-file:`Python/opcode_targets.h` by running ``make regen-opcode regen-opcode-targets``. With a new bytecode you must also change what is called the magic number for .pyc files. The variable ``MAGIC_NUMBER`` in -:file:`Lib/importlib/_bootstrap_external.py` contains the number. +:cpy-file:`Lib/importlib/_bootstrap_external.py` contains the number. Changing this number will lead to all .pyc files with the old ``MAGIC_NUMBER`` to be recompiled by the interpreter on import. Whenever ``MAGIC_NUMBER`` is -changed, the ranges in the ``magic_values`` array in :file:`PC/launcher.c` -must also be updated. Changes to :file:`Lib/importlib/_bootstrap_external.py` +changed, the ranges in the ``magic_values`` array in :cpy-file:`PC/launcher.c` +must also be updated. Changes to :cpy-file:`Lib/importlib/_bootstrap_external.py` will take effect only after running ``make regen-importlib``. Running this -command before adding the new bytecode target to :file:`Python/ceval.c` will +command before adding the new bytecode target to :cpy-file:`Python/ceval.c` will result in an error. You should only run ``make regen-importlib`` after the new bytecode target has been added. @@ -483,13 +486,13 @@ bytecode target has been added. regenerate the required files without requiring additional arguments. Finally, you need to introduce the use of the new bytecode. Altering -:file:`Python/compile.c` and :file:`Python/ceval.c` will be the primary places -to change. You must add the case for a new opcode into the 'switch' -statement in the ``stack_effect()`` function in :file:`Python/compile.c`. +:cpy-file:`Python/compile.c` and :cpy-file:`Python/ceval.c` will be the primary +places to change. You must add the case for a new opcode into the 'switch' +statement in the ``stack_effect()`` function in :cpy-file:`Python/compile.c`. If the new opcode has a jump target, you will need to update macros and -'switch' statements in :file:`Python/peephole.c`. If it affects a control +'switch' statements in :cpy-file:`Python/peephole.c`. If it affects a control flow or the block stack, you may have to update the ``frame_setlineno()`` -function in :file:`Objects/frameobject.c`. :file:`Lib/dis.py` may need +function in :cpy-file:`Objects/frameobject.c`. :cpy-file:`Lib/dis.py` may need an update if the new opcode interprets its argument in a special way (like ``FORMAT_VALUE`` or ``MAKE_FUNCTION``). @@ -511,9 +514,9 @@ Code Objects ============ The result of ``PyAST_CompileObject()`` is a ``PyCodeObject`` which is defined in -:file:`Include/code.h`. And with that you now have executable Python bytecode! +:cpy-file:`Include/code.h`. And with that you now have executable Python bytecode! -The code objects (byte code) are executed in :file:`Python/ceval.c`. This file +The code objects (byte code) are executed in :cpy-file:`Python/ceval.c`. This file will also need a new case statement for the new opcode in the big switch statement in ``_PyEval_EvalFrameDefault()``. @@ -532,12 +535,12 @@ Important Files asdl_c.py "Generate C code from an ASDL description." Generates - :file:`Python/Python-ast.c` and :file:`Include/Internal/pycore_ast.h`. + :cpy-file:`Python/Python-ast.c` and :cpy-file:`Include/Internal/pycore_ast.h`. parser.c The new PEG parser introduced in Python 3.9. - Generated by :file:`Tools/peg_generator/pegen/c_generator.py` - from the grammar :file:`Grammar/python.gram`. Creates the AST from + Generated by :cpy-file:`Tools/peg_generator/pegen/c_generator.py` + from the grammar :cpy-file:`Grammar/python.gram`. Creates the AST from source code. Rule functions for their corresponding production rules are found here. @@ -547,12 +550,12 @@ Important Files pegen.c Contains helper functions which are used by functions in - :file:`Parser/parser.c` to construct the AST. Also contains helper + :cpy-file:`Parser/parser.c` to construct the AST. Also contains helper functions which help raise better error messages when parsing source code. pegen.h - Header file for the corresponding :file:`Parser/pegen.c`. Also contains + Header file for the corresponding :cpy-file:`Parser/pegen.c`. Also contains definitions of the ``Parser`` and ``Token`` structs. + Python/ @@ -560,15 +563,15 @@ Important Files Python-ast.c Creates C structs corresponding to the ASDL types. Also contains code for marshalling AST nodes (core ASDL types have - marshalling code in :file:`asdl.c`). "File automatically generated by - :file:`Parser/asdl_c.py`". This file must be committed separately + marshalling code in :cpy-file:`asdl.c`). "File automatically generated by + :cpy-file:`Parser/asdl_c.py`". This file must be committed separately after every grammar change is committed since the ``__version__`` value is set to the latest grammar change revision number. asdl.c Contains code to handle the ASDL sequence type. Also has code to handle marshalling the core ASDL types, such as number and - identifier. Used by :file:`Python-ast.c` for marshalling AST nodes. + identifier. Used by :cpy-file:`Python-ast.c` for marshalling AST nodes. ast.c Used for validating the AST. @@ -599,46 +602,46 @@ Important Files Helpers for generating bytecode. opcode_targets.h - One of the files that must be modified if :file:`Lib/opcode.py` is. + One of the files that must be modified if :cpy-file:`Lib/opcode.py` is. + Include/ code.h - Header file for :file:`Objects/codeobject.c`; contains definition of + Header file for :cpy-file:`Objects/codeobject.c`; contains definition of ``PyCodeObject``. opcode.h - One of the files that must be modified if :file:`Lib/opcode.py` is. + One of the files that must be modified if :cpy-file:`Lib/opcode.py` is. + Internal/ pycore_ast.h Contains the actual definitions of the C structs as generated by - :file:`Python/Python-ast.c`. - "Automatically generated by :file:`Parser/asdl_c.py`". + :cpy-file:`Python/Python-ast.c`. + "Automatically generated by :cpy-file:`Parser/asdl_c.py`". pycore_asdl.h - Header for the corresponding :file:`Python/ast.c` + Header for the corresponding :cpy-file:`Python/ast.c` pycore_ast.h - Declares ``_PyAST_Validate()`` external (from :file:`Python/ast.c`). + Declares ``_PyAST_Validate()`` external (from :cpy-file:`Python/ast.c`). pycore_symtable.h - Header for :file:`Python/symtable.c`. ``struct symtable`` and + Header for :cpy-file:`Python/symtable.c`. ``struct symtable`` and ``PySTEntryObject`` are defined here. pycore_parser.h - Header for the corresponding :file:`Parser/peg_api.c`. + Header for the corresponding :cpy-file:`Parser/peg_api.c`. pycore_pyarena.h - Header file for the corresponding :file:`Python/pyarena.c`. + Header file for the corresponding :cpy-file:`Python/pyarena.c`. + Objects/ codeobject.c Contains PyCodeObject-related code (originally in - :file:`Python/compile.c`). + :cpy-file:`Python/compile.c`). frameobject.c Contains the ``frame_setlineno()`` function which should determine diff --git a/internals/exploring.rst b/internals/exploring.rst index f27c150c0e..b049159af8 100644 --- a/internals/exploring.rst +++ b/internals/exploring.rst @@ -32,21 +32,21 @@ For builtin types, the typical layout is: * :file:`Objects/{}object.c` * :file:`Lib/test/test_{}.py` -* :file:`Doc/library/stdtypes.rst` +* :cpy-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` +* :cpy-file:`Python/bltinmodule.c` +* :cpy-file:`Lib/test/test_builtin.py` +* :cpy-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` +* builtin type ``int`` is at :cpy-file:`Objects/longobject.c` +* builtin type ``str`` is at :cpy-file:`Objects/unicodeobject.c` +* builtin module ``sys`` is at :cpy-file:`Python/sysmodule.c` +* builtin module ``marshal`` is at :cpy-file:`Python/marshal.c` +* Windows-only module ``winreg`` is at :cpy-file:`PC/winreg.c` Additional References From a65508a31441f465d038334ed57b6fde9eeba9ae Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sun, 13 Nov 2022 21:57:01 -0700 Subject: [PATCH 2/2] Fix broken file paths. --- core-developers/experts.rst | 2 +- developer-workflow/c-api.rst | 2 +- internals/compiler.rst | 22 ++++++++++++---------- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/core-developers/experts.rst b/core-developers/experts.rst index 95f9e922e1..03b0747fc1 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -17,7 +17,7 @@ while any other issues can and should be decided by any committer. Developers can choose to follow labels, so if a label that they are following is added to an issue or pull request, they will be notified -automatically. The :cpy-file:`CODEOWNERS` file is also used to indicate +automatically. The :cpy-file:`.github/CODEOWNERS` file is also used to indicate maintainers that will be automatically added as reviewers to pull requests. Unless a name is followed by a '*', you should never assign an issue to diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index a85ad34428..92e55330d8 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -101,7 +101,7 @@ C API Tests Tests for the public C API live in the ``_testcapi`` module. Functions named ``test_*`` are used as tests directly. Tests that need Python code (or are just easier to partially write in Python) -live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi.py`. +live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi`. Due to its size, the ``_testcapi`` module is defined in several source files. diff --git a/internals/compiler.rst b/internals/compiler.rst index 8ed57b9df6..9e780def33 100644 --- a/internals/compiler.rst +++ b/internals/compiler.rst @@ -143,7 +143,7 @@ In general, unless you are working on the critical core of the compiler, memory management can be completely ignored. But if you are working at either the very beginning of the compiler or the end, you need to care about how the arena works. All code relating to the arena is in either -:cpy-file:`Include/Internal/pycore_pyarena.h` or :cpy-file:`Python/pyarena.c`. +:cpy-file:`Include/internal/pycore_pyarena.h` or :cpy-file:`Python/pyarena.c`. ``PyArena_New()`` will create a new arena. The returned ``PyArena`` structure will store pointers to all memory given to it. This does the bookkeeping of @@ -243,7 +243,7 @@ There are macros for creating and using ``asdl_xx_seq *`` types, where *xx* is a type of the ASDL sequence. Three main types are defined manually -- ``generic``, ``identifier`` and ``int``. These types are found in :cpy-file:`Python/asdl.c` and its corresponding header file -:cpy-file:`Include/Internal/pycore_asdl.h`. Functions and macros +:cpy-file:`Include/internal/pycore_asdl.h`. Functions and macros for creating ``asdl_xx_seq *`` types are as follows: ``_Py_asdl_generic_seq_new(Py_ssize_t, PyArena *)`` @@ -255,7 +255,7 @@ for creating ``asdl_xx_seq *`` types are as follows: In addition to the three types mentioned above, some ASDL sequence types are automatically generated by :cpy-file:`Parser/asdl_c.py` and found in -:cpy-file:`Include/Internal/pycore_ast.h`. Macros for using both manually +:cpy-file:`Include/internal/pycore_ast.h`. Macros for using both manually defined and automatically generated ASDL sequence types are as follows: ``asdl_seq_GET(asdl_xx_seq *, int)`` @@ -535,7 +535,7 @@ Important Files asdl_c.py "Generate C code from an ASDL description." Generates - :cpy-file:`Python/Python-ast.c` and :cpy-file:`Include/Internal/pycore_ast.h`. + :cpy-file:`Python/Python-ast.c` and :cpy-file:`Include/internal/pycore_ast.h`. parser.c The new PEG parser introduced in Python 3.9. @@ -563,15 +563,17 @@ Important Files Python-ast.c Creates C structs corresponding to the ASDL types. Also contains code for marshalling AST nodes (core ASDL types have - marshalling code in :cpy-file:`asdl.c`). "File automatically generated by - :cpy-file:`Parser/asdl_c.py`". This file must be committed separately - after every grammar change is committed since the ``__version__`` - value is set to the latest grammar change revision number. + marshalling code in :cpy-file:`Python/asdl.c`). "File automatically + generated by :cpy-file:`Parser/asdl_c.py`". This file must be + committed separately after every grammar change is committed since + the ``__version__`` value is set to the latest grammar change + revision number. asdl.c Contains code to handle the ASDL sequence type. Also has code to handle marshalling the core ASDL types, such as number and - identifier. Used by :cpy-file:`Python-ast.c` for marshalling AST nodes. + identifier. Used by :cpy-file:`Python/Python-ast.c` for marshalling + AST nodes. ast.c Used for validating the AST. @@ -613,7 +615,7 @@ Important Files opcode.h One of the files that must be modified if :cpy-file:`Lib/opcode.py` is. - + Internal/ + + internal/ pycore_ast.h Contains the actual definitions of the C structs as generated by