gh-127833: Reword and expand the Notation section#134443
Merged
Uh oh!
There was an error while loading. Please reload this page.
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
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>
MemberAuthor
encukou commented May 21, 2025
@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>
Member
lysnikolaou commented May 28, 2025
I'll have a look at this tomorrow if that's okay. |
Member
lysnikolaou left a comment
lysnikolaou left a comment There was a problem hiding this comment.
Looks great in general! Left a few not-so-significant comments inline
Uh oh!
There was an error while loading. Please reload this page.
Doc/reference/introduction.rst Outdated
Comment on lines 132 to 136
| * ``"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>``). |
Member
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?
MemberAuthor
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. |
Member
There was a problem hiding this comment.
What possibilities exist, other than referencing another rule?
MemberAuthor
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.
cmarqu reviewed May 29, 2025
Uh oh!
There was an error while loading. Please reload this page.
Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com> Co-authored-by: Colin Marquardt <cmarqu42@gmail.com>
encukou commented Jun 7, 2025
Uh oh!
There was an error while loading. Please reload this page.
MemberAuthor
encukou commented Jun 9, 2025
Thanks for the reviews! |
encukou merged commit 28d91d0 into python:main 26 checks passed
Uh oh!
There was an error while loading. Please reload this page.
Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14. |
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jun 9, 2025
) 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. |
encukou added a commit that referenced this pull request Jun 9, 2025
…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>
lkollar pushed a commit to lkollar/cpython that referenced this pull request Jun 19, 2025
) 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. 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>
Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025
) 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. 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>
taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
) 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. 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>
Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
) 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. 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>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/