Skip to content

Commit e0fa2bd

Browse files
authored
Reformat "Important Files" section in compiler.rst (#1004)
* Reformat the "Important file" section. * More reformatting.
1 parent 40955c4 commit e0fa2bd

File tree

1 file changed

+76
-104
lines changed

1 file changed

+76
-104
lines changed

internals/compiler.rst

Lines changed: 76 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -524,140 +524,112 @@ statement in ``_PyEval_EvalFrameDefault()``.
524524
Important Files
525525
===============
526526

527-
+ Parser/
527+
* :cpy-file:`Parser/`
528+
* :cpy-file:`Parser/Python.asdl`: ASDL syntax file.
528529

529-
Python.asdl
530-
ASDL syntax file
530+
* :cpy-file:`Parser/asdl.py`: Parser for ASDL definition files.
531+
Reads in an ASDL description and parses it into an AST that describes it.
531532

532-
asdl.py
533-
Parser for ASDL definition files. Reads in an ASDL description
534-
and parses it into an AST that describes it.
533+
* :cpy-file:`Parser/asdl_c.py`: Generate C code from an ASDL description.
534+
Generates :cpy-file:`Python/Python-ast.c` and
535+
:cpy-file:`Include/internal/pycore_ast.h`.
535536

536-
asdl_c.py
537-
"Generate C code from an ASDL description." Generates
538-
:cpy-file:`Python/Python-ast.c` and :cpy-file:`Include/internal/pycore_ast.h`.
537+
* :cpy-file:`Parser/parser.c`: The new PEG parser introduced in Python 3.9.
538+
Generated by :cpy-file:`Tools/peg_generator/pegen/c_generator.py`
539+
from the grammar :cpy-file:`Grammar/python.gram`. Creates the AST from
540+
source code. Rule functions for their corresponding production rules
541+
are found here.
539542

540-
parser.c
541-
The new PEG parser introduced in Python 3.9.
542-
Generated by :cpy-file:`Tools/peg_generator/pegen/c_generator.py`
543-
from the grammar :cpy-file:`Grammar/python.gram`. Creates the AST from
544-
source code. Rule functions for their corresponding production rules
545-
are found here.
543+
* :cpy-file:`Parser/peg_api.c`: Contains high-level functions which are
544+
used by the interpreter to create an AST from source code.
546545

547-
peg_api.c
548-
Contains high-level functions which are used by the interpreter to
549-
create an AST from source code .
546+
* :cpy-file:`Parser/pegen.c`: Contains helper functions which are used
547+
by functions in :cpy-file:`Parser/parser.c` to construct the AST.
548+
Also contains helper functions which help raise better error messages
549+
when parsing source code.
550550

551-
pegen.c
552-
Contains helper functions which are used by functions in
553-
:cpy-file:`Parser/parser.c` to construct the AST. Also contains helper
554-
functions which help raise better error messages when parsing source
555-
code.
551+
* :cpy-file:`Parser/pegen.h`: Header file for the corresponding
552+
:cpy-file:`Parser/pegen.c`. Also contains definitions of the ``Parser``
553+
and ``Token`` structs.
556554

557-
pegen.h
558-
Header file for the corresponding :cpy-file:`Parser/pegen.c`. Also contains
559-
definitions of the ``Parser`` and ``Token`` structs.
555+
* :cpy-file:`Python/`
556+
* :cpy-file:`Python/Python-ast.c`: Creates C structs corresponding to
557+
the ASDL types. Also contains code for marshalling AST nodes (core
558+
ASDL types have marshalling code in :cpy-file:`Python/asdl.c`).
559+
"File automatically generated by :cpy-file:`Parser/asdl_c.py`".
560+
This file must be committed separately after every grammar change
561+
is committed since the ``__version__`` value is set to the latest
562+
grammar change revision number.
560563

561-
+ Python/
564+
* :cpy-file:`Python/asdl.c`: Contains code to handle the ASDL sequence type.
565+
Also has code to handle marshalling the core ASDL types, such as number
566+
and identifier. Used by :cpy-file:`Python/Python-ast.c` for marshalling
567+
AST nodes.
562568

563-
Python-ast.c
564-
Creates C structs corresponding to the ASDL types. Also
565-
contains code for marshalling AST nodes (core ASDL types have
566-
marshalling code in :cpy-file:`Python/asdl.c`). "File automatically
567-
generated by :cpy-file:`Parser/asdl_c.py`". This file must be
568-
committed separately after every grammar change is committed since
569-
the ``__version__`` value is set to the latest grammar change
570-
revision number.
569+
* :cpy-file:`Python/ast.c`: Used for validating the AST.
571570

572-
asdl.c
573-
Contains code to handle the ASDL sequence type. Also has code
574-
to handle marshalling the core ASDL types, such as number and
575-
identifier. Used by :cpy-file:`Python/Python-ast.c` for marshalling
576-
AST nodes.
571+
* :cpy-file:`Python/ast_opt.c`: Optimizes the AST.
577572

578-
ast.c
579-
Used for validating the AST.
573+
* :cpy-file:`Python/ast_unparse.c`: Converts the AST expression node
574+
back into a string (for string annotations).
580575

581-
ast_opt.c
582-
Optimizes the AST.
576+
* :cpy-file:`Python/ceval.c`: Executes byte code (aka, eval loop).
583577

584-
ast_unparse.c
585-
Converts the AST expression node back into a string
586-
(for string annotations).
578+
* :cpy-file:`Python/compile.c`: Emits bytecode based on the AST.
587579

588-
ceval.c
589-
Executes byte code (aka, eval loop).
580+
* :cpy-file:`Python/symtable.c`: Generates a symbol table from AST.
590581

591-
compile.c
592-
Emits bytecode based on the AST.
582+
* :cpy-file:`Python/peephole.c`: Optimizes the bytecode.
593583

594-
symtable.c
595-
Generates a symbol table from AST.
584+
* :cpy-file:`Python/pyarena.c`: Implementation of the arena memory manager.
596585

597-
peephole.c
598-
Optimizes the bytecode.
586+
* :cpy-file:`Python/wordcode_helpers.h`: Helpers for generating bytecode.
599587

600-
pyarena.c
601-
Implementation of the arena memory manager.
588+
* :cpy-file:`Python/opcode_targets.h`: One of the files that must be
589+
modified if :cpy-file:`Lib/opcode.py` is.
602590

603-
wordcode_helpers.h
604-
Helpers for generating bytecode.
591+
* :cpy-file:`Include/`
592+
* :cpy-file:`Include/code.h`: Header file for :cpy-file:`Objects/codeobject.c`;
593+
contains definition of ``PyCodeObject``.
605594

606-
opcode_targets.h
607-
One of the files that must be modified if :cpy-file:`Lib/opcode.py` is.
595+
* :cpy-file:`Include/opcode.h`: One of the files that must be modified if
596+
:cpy-file:`Lib/opcode.py` is.
608597

609-
+ Include/
598+
* :cpy-file:`Include/internal/pycore_ast.h`: Contains the actual definitions
599+
of the C structs as generated by :cpy-file:`Python/Python-ast.c`.
600+
"Automatically generated by :cpy-file:`Parser/asdl_c.py`".
610601

611-
code.h
612-
Header file for :cpy-file:`Objects/codeobject.c`; contains definition of
613-
``PyCodeObject``.
602+
* :cpy-file:`Include/internal/pycore_asdl.h`: Header for the corresponding
603+
:cpy-file:`Python/ast.c`.
614604

615-
opcode.h
616-
One of the files that must be modified if :cpy-file:`Lib/opcode.py` is.
605+
* :cpy-file:`Include/internal/pycore_ast.h`: Declares ``_PyAST_Validate()``
606+
external (from :cpy-file:`Python/ast.c`).
617607

618-
+ internal/
608+
* :cpy-file:`Include/internal/pycore_symtable.h`: Header for
609+
:cpy-file:`Python/symtable.c`. ``struct symtable`` and ``PySTEntryObject``
610+
are defined here.
619611

620-
pycore_ast.h
621-
Contains the actual definitions of the C structs as generated by
622-
:cpy-file:`Python/Python-ast.c`.
623-
"Automatically generated by :cpy-file:`Parser/asdl_c.py`".
612+
* :cpy-file:`Include/internal/pycore_parser.h`: Header for the
613+
corresponding :cpy-file:`Parser/peg_api.c`.
624614

625-
pycore_asdl.h
626-
Header for the corresponding :cpy-file:`Python/ast.c`
615+
* :cpy-file:`Include/internal/pycore_pyarena.h`: Header file for the
616+
corresponding :cpy-file:`Python/pyarena.c`.
627617

628-
pycore_ast.h
629-
Declares ``_PyAST_Validate()`` external (from :cpy-file:`Python/ast.c`).
618+
* :cpy-file:`Objects/`
619+
* :cpy-file:`Objects/codeobject.c`: Contains PyCodeObject-related code
620+
(originally in :cpy-file:`Python/compile.c`).
630621

631-
pycore_symtable.h
632-
Header for :cpy-file:`Python/symtable.c`. ``struct symtable`` and
633-
``PySTEntryObject`` are defined here.
622+
* :cpy-file:`Objects/frameobject.c`: Contains the ``frame_setlineno()``
623+
function which should determine whether it is allowed to make a jump
624+
between two points in a bytecode.
634625

635-
pycore_parser.h
636-
Header for the corresponding :cpy-file:`Parser/peg_api.c`.
626+
* :cpy-file:`Lib/`
627+
* :cpy-file:`Lib/opcode.py`: Master list of bytecode; if this file is
628+
modified you must modify several other files accordingly
629+
(see "`Introducing New Bytecode`_")
637630

638-
pycore_pyarena.h
639-
Header file for the corresponding :cpy-file:`Python/pyarena.c`.
640-
641-
642-
+ Objects/
643-
644-
codeobject.c
645-
Contains PyCodeObject-related code (originally in
646-
:cpy-file:`Python/compile.c`).
647-
648-
frameobject.c
649-
Contains the ``frame_setlineno()`` function which should determine
650-
whether it is allowed to make a jump between two points in a bytecode.
651-
652-
+ Lib/
653-
654-
opcode.py
655-
Master list of bytecode; if this file is modified you must modify
656-
several other files accordingly (see "`Introducing New Bytecode`_")
657-
658-
importlib/_bootstrap_external.py
659-
Home of the magic number (named ``MAGIC_NUMBER``) for bytecode
660-
versioning.
631+
* :cpy-file:`Lib/importlib/_bootstrap_external.py`: Home of the magic number
632+
(named ``MAGIC_NUMBER``) for bytecode versioning.
661633

662634

663635
Known Compiler-related Experiments

0 commit comments

Comments
 (0)