Skip to content

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 our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from

Conversation

encukou
Copy link
Member

@encukou encukou commented May 21, 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.

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/

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.
@encukou encukou force-pushed the grammar-notation branch from 5cf68f6 to ec90d40 Compare May 21, 2025 16:06
@encukou
Copy link
Member Author

encukou commented May 21, 2025

@lysnikolaou, does this look correct to you?
Rendered docs: notation section, full grammar

@encukou encukou marked this pull request as ready for review May 28, 2025 16:08
@lysnikolaou
Copy link
Member

I'll have a look at this tomorrow if that's okay.

Copy link
Member

@lysnikolaou lysnikolaou left a 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

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>``).
Copy link
Member

@lysnikolaou lysnikolaou May 29, 2025

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?

Copy link
Member Author

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.
Copy link
Member

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?

Copy link
Member Author

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 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting core review docs Documentation in the Doc dir skip news
Projects
Status: Todo
Development

Successfully merging this pull request may close these issues.

3 participants