gh-127833: Reword and expand the Notation section #134443
Conversation
Prepare the docs for using the notation used in the `python.gram` file. If we want to sync the two, the meta-syntax should be the same. Also, remove the distinction between lexical and syntactic rules. With f- and t-strings, the line between the two is blurry.
Co-authored-by: Blaise Pabon <blaise@gmail.com>
|
@lysnikolaou, does this look correct to you? |
Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
|
I'll have a look at this tomorrow if that's okay. |
Doc/reference/introduction.rst
Outdated
| * ``"a"..."z"``: Two literal characters separated by three dots mean a choice | ||
| of any single character in the given (inclusive) range of ASCII characters. | ||
| * ``<...>``: A phrase between angular brackets gives an informal description | ||
| of the matched symbol (for example, ``<any ASCII character except "\">``), | ||
| or an abbreviation that is defined in nearby text (for example, ``<Lu>``). |
There was a problem hiding this comment.
Should we be mentioning somewhere that these are not part of the actual Python grammar, but part of the notation to make it easier to describe specific constructs? Maybe as part of the first paragraph that says that this is a mixture of EBNF and PEG?
There was a problem hiding this comment.
I moved them to the end, and (re-)added notes that they're only used in the lexer definitions.
| The definition to the right of the colon uses the following syntax elements: | ||
|
|
||
| * ``name``: A name refers to another rule. | ||
| Where possible, it is a link to the rule's definition. |
There was a problem hiding this comment.
What possibilities exist, other than referencing another rule?
There was a problem hiding this comment.
Rules that aren't defined by formal grammar in the docs, for example strings in https://docs.python.org/3/reference/compound_stmts.html#literal-patterns
I consider these to be issues that #127833 should eventually fix, but until then I'd keep the weasel word in.
Also: tokens are currently unlinked, and many don't have a (lexical) grammar rule so they should eventually link to prose.
Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com> Co-authored-by: Colin Marquardt <cmarqu42@gmail.com>
|
Thanks for the reviews! |
|
Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14. |
) Prepare the docs for using the notation used in the `python.gram` file. If we want to sync the two, the meta-syntax should be the same. Link the Full Grammar docs here; keep only a few extras. Also, remove the distinction between lexical and syntactic rules, except for whitespace handling. With f- and t-strings, the line between the two is blurry. (cherry picked from commit 28d91d0) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com> Co-authored-by: Colin Marquardt <cmarqu42@gmail.com>
|
GH-135301 is a backport of this pull request to the 3.14 branch. |
…H-135301) Prepare the docs for using the notation used in the `python.gram` file. If we want to sync the two, the meta-syntax should be the same. Link the Full Grammar docs here; keep only a few extras. Also, remove the distinction between lexical and syntactic rules, except for whitespace handling. With f- and t-strings, the line between the two is blurry. (cherry picked from commit 28d91d0) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com> Co-authored-by: Colin Marquardt <cmarqu42@gmail.com>
Prepare the docs for using the notation used in the
python.gramfile. If we want to sync the two, the meta-syntax should be the same.Also, remove the distinction between lexical and syntactic rules.
With f- and t-strings, the line between the two is blurry.
📚 Documentation preview 📚: https://cpython-previews--134443.org.readthedocs.build/