Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork32.1k
gh-127833: Reword and expand the Notation section#134443
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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
| * ``"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>``). |
lysnikolaouMay 29, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
What possibilities exist, other than referencing another rule?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Rules that aren't defined by formal grammar in the docs, for examplestrings inhttps://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 theyshould eventually link to prose.
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>
Uh oh!
There was an error while loading.Please reload this page.
Thanks for the reviews! |
28d91d0 intopython:mainUh 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. |
)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 commit28d91d0)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 the3.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 commit28d91d0)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>
Uh oh!
There was an error while loading.Please reload this page.
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/