diff --git a/internals/compiler.rst b/internals/compiler.rst index d7853456d..775540f54 100644 --- a/internals/compiler.rst +++ b/internals/compiler.rst @@ -511,107 +511,112 @@ Important files =============== * :cpy-file:`Parser/` - * :cpy-file:`Parser/Python.asdl`: ASDL syntax file. - * :cpy-file:`Parser/asdl.py`: Parser for ASDL definition files. - Reads in an ASDL description and parses it into an AST that describes it. + * :cpy-file:`Parser/Python.asdl`: ASDL syntax file. - * :cpy-file:`Parser/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:`Parser/asdl.py`: Parser for ASDL definition files. + Reads in an ASDL description and parses it into an AST that describes it. - * :cpy-file:`Parser/parser.c`: The new PEG parser introduced in Python 3.9. - 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. + * :cpy-file:`Parser/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:`Parser/peg_api.c`: Contains high-level functions which are - used by the interpreter to create an AST from source code. + * :cpy-file:`Parser/parser.c`: The new PEG parser introduced in Python 3.9. + 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. - * :cpy-file:`Parser/pegen.c`: Contains helper functions which are used - by functions in :cpy-file:`Parser/parser.c` to construct the AST. - Also contains helper functions which help raise better error messages - when parsing source code. + * :cpy-file:`Parser/peg_api.c`: Contains high-level functions which are + used by the interpreter to create an AST from source code. - * :cpy-file:`Parser/pegen.h`: Header file for the corresponding - :cpy-file:`Parser/pegen.c`. Also contains definitions of the ``Parser`` - and ``Token`` structs. + * :cpy-file:`Parser/pegen.c`: Contains helper functions which are used + by functions in :cpy-file:`Parser/parser.c` to construct the AST. + Also contains helper functions which help raise better error messages + when parsing source code. + + * :cpy-file:`Parser/pegen.h`: Header file for the corresponding + :cpy-file:`Parser/pegen.c`. Also contains definitions of the ``Parser`` + and ``Token`` structs. * :cpy-file:`Python/` - * :cpy-file:`Python/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:`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. - * :cpy-file:`Python/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/Python-ast.c` for marshalling - AST nodes. + * :cpy-file:`Python/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:`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. + + * :cpy-file:`Python/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/Python-ast.c` for marshalling + AST nodes. - * :cpy-file:`Python/ast.c`: Used for validating the AST. + * :cpy-file:`Python/ast.c`: Used for validating the AST. - * :cpy-file:`Python/ast_opt.c`: Optimizes the AST. + * :cpy-file:`Python/ast_opt.c`: Optimizes the AST. - * :cpy-file:`Python/ast_unparse.c`: Converts the AST expression node - back into a string (for string annotations). + * :cpy-file:`Python/ast_unparse.c`: Converts the AST expression node + back into a string (for string annotations). - * :cpy-file:`Python/ceval.c`: Executes byte code (aka, eval loop). + * :cpy-file:`Python/ceval.c`: Executes byte code (aka, eval loop). - * :cpy-file:`Python/compile.c`: Emits bytecode based on the AST. + * :cpy-file:`Python/compile.c`: Emits bytecode based on the AST. - * :cpy-file:`Python/symtable.c`: Generates a symbol table from AST. + * :cpy-file:`Python/symtable.c`: Generates a symbol table from AST. - * :cpy-file:`Python/pyarena.c`: Implementation of the arena memory manager. + * :cpy-file:`Python/pyarena.c`: Implementation of the arena memory manager. - * :cpy-file:`Python/opcode_targets.h`: One of the files that must be - modified if :cpy-file:`Lib/opcode.py` is. + * :cpy-file:`Python/opcode_targets.h`: One of the files that must be + modified if :cpy-file:`Lib/opcode.py` is. * :cpy-file:`Include/` - * :cpy-file:`Include/cpython/code.h`: Header file for - :cpy-file:`Objects/codeobject.c`; contains definition of ``PyCodeObject``. - * :cpy-file:`Include/opcode.h`: One of the files that must be modified if - :cpy-file:`Lib/opcode.py` is. + * :cpy-file:`Include/cpython/code.h`: Header file for + :cpy-file:`Objects/codeobject.c`; contains definition of ``PyCodeObject``. + + * :cpy-file:`Include/opcode.h`: One of the files that must be modified if + :cpy-file:`Lib/opcode.py` is. - * :cpy-file:`Include/internal/pycore_ast.h`: Contains the actual definitions - of the C structs as generated by :cpy-file:`Python/Python-ast.c`. - "Automatically generated by :cpy-file:`Parser/asdl_c.py`". + * :cpy-file:`Include/internal/pycore_ast.h`: Contains the actual definitions + of the C structs as generated by :cpy-file:`Python/Python-ast.c`. + "Automatically generated by :cpy-file:`Parser/asdl_c.py`". - * :cpy-file:`Include/internal/pycore_asdl.h`: Header for the corresponding - :cpy-file:`Python/ast.c`. + * :cpy-file:`Include/internal/pycore_asdl.h`: Header for the corresponding + :cpy-file:`Python/ast.c`. - * :cpy-file:`Include/internal/pycore_ast.h`: Declares ``_PyAST_Validate()`` - external (from :cpy-file:`Python/ast.c`). + * :cpy-file:`Include/internal/pycore_ast.h`: Declares ``_PyAST_Validate()`` + external (from :cpy-file:`Python/ast.c`). - * :cpy-file:`Include/internal/pycore_symtable.h`: Header for - :cpy-file:`Python/symtable.c`. ``struct symtable`` and ``PySTEntryObject`` - are defined here. + * :cpy-file:`Include/internal/pycore_symtable.h`: Header for + :cpy-file:`Python/symtable.c`. ``struct symtable`` and ``PySTEntryObject`` + are defined here. - * :cpy-file:`Include/internal/pycore_parser.h`: Header for the - corresponding :cpy-file:`Parser/peg_api.c`. + * :cpy-file:`Include/internal/pycore_parser.h`: Header for the + corresponding :cpy-file:`Parser/peg_api.c`. - * :cpy-file:`Include/internal/pycore_pyarena.h`: Header file for the - corresponding :cpy-file:`Python/pyarena.c`. + * :cpy-file:`Include/internal/pycore_pyarena.h`: Header file for the + corresponding :cpy-file:`Python/pyarena.c`. * :cpy-file:`Objects/` - * :cpy-file:`Objects/codeobject.c`: Contains PyCodeObject-related code - (originally in :cpy-file:`Python/compile.c`). - * :cpy-file:`Objects/frameobject.c`: Contains the ``frame_setlineno()`` - function which should determine whether it is allowed to make a jump - between two points in a bytecode. + * :cpy-file:`Objects/codeobject.c`: Contains PyCodeObject-related code + (originally in :cpy-file:`Python/compile.c`). + + * :cpy-file:`Objects/frameobject.c`: Contains the ``frame_setlineno()`` + function which should determine whether it is allowed to make a jump + between two points in a bytecode. * :cpy-file:`Lib/` - * :cpy-file:`Lib/opcode.py`: Master list of bytecode; if this file is - modified you must modify several other files accordingly - (see "`Introducing New Bytecode`_") - * :cpy-file:`Lib/importlib/_bootstrap_external.py`: Home of the magic number - (named ``MAGIC_NUMBER``) for bytecode versioning. + * :cpy-file:`Lib/opcode.py`: Master list of bytecode; if this file is + modified you must modify several other files accordingly + (see "`Introducing New Bytecode`_") + + * :cpy-file:`Lib/importlib/_bootstrap_external.py`: Home of the magic number + (named ``MAGIC_NUMBER``) for bytecode versioning. Known compiler-related experiments