Description

dhruvmanila

opened on Mar 11, 2024

Issue body actions

Documentation

Apologies if this is tracked somewhere else, I couldn't find it.

I'm looking at the f-string section in the "Lexical analysis" page and the grammar is not yet updated with the implementation of PEP 701: https://docs.python.org/3.12/reference/lexical_analysis.html#formatted-string-literals while it is so on the "Full Grammar specification" page: https://docs.python.org/3.13/reference/grammar.html.

The main use case for this is to link to the f-string grammar. It's difficult to do so on the "Full Grammar specification" page but it's easy on an individual section.

Activity

1. dhruvmanila

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Mar 11, 2024
2. terryjreedy commented on Mar 11, 2024

   

   terryjreedy

   on Mar 11, 2024

   Member

   More actions

   @pablogsal
3. lysnikolaou commented on Mar 11, 2024

   

   lysnikolaou

   on Mar 11, 2024

   Member

   More actions

   I'm not sure whether this is the way to go.

   The full grammar specification is generated from the grammar file itself (although stripped down quite a bit).In the lexical analysis page, there's grammars for many different syntactic constructs of the language that are directed to humans and are written in a way that should reflect that. They're also all consistent in the syntax they use, so changing only one place and have it written in PEG feels a bit odd.

   If all you care about is being able to link to the f-string grammar for other people to read, then that grammar in the lexical analysis page is certainly good enough and covers what the real PEG grammar should be able to cover as well. If you want to link to the real grammar that's used at runtime, linking to https://github.com/python/cpython/blob/main/Grammar/python.gram#L912-L927 is probably good enough?
4. hugovk commented on Mar 12, 2024

   

   hugovk

   on Mar 12, 2024

   Member

   More actions

   Also cc @encukou who was been working on grammar docs.
5. encukou commented on Mar 12, 2024

   

   encukou

   on Mar 12, 2024

   Member

   More actions

   Yeah, I'm giving a bit of time each week to generating docs from the actual grammar, and hope to do it by 3.13. But i want to look at f-strings (and other topics that need touch lexical docs) last.
6. dhruvmanila commented on Mar 12, 2024

   

   dhruvmanila

   on Mar 12, 2024

   Author

   More actions

   They're also all consistent in the syntax they use, so changing only one place and have it written in PEG feels a bit odd.

   Yeah, I agree. I wasn't aware of that.

   If you want to link to the real grammar that's used at runtime, linking to main/Grammar/python.gram#L912-L927 is probably good enough?

   It should be good enough although I would still prefer have it link to the language reference to include any contextual information as well.

   @encukou Thank you! If there's a tracking issue for the same, we can merge this into it otherwise I leave it at your discretion to keep this open or not. I'm fine closing it.
7. encukou commented on Mar 12, 2024

   

   encukou

   on Mar 12, 2024

   Member

   More actions

   No issue yet, just discussion.
   I'll assign this to myself: it might be a few months before I get to this, but do talk to me if you want to start working on it earlier :)

   Reacted by Dhruv Manilawala
8. encukou

   self-assigned this

   on Mar 12, 2024
9. AlexWaygood

   added

   topic-parser

   on Mar 12, 2024
10. StanFromIreland

    linked a pull request that will close this issuegh-135676: Reword the f-string (and t-string) section #137469on Aug 22, 2025
11. StanFromIreland

    added a parent issue on Aug 22, 2025

    • Reword the Lexical Analysis chapter of the docs #135676
12. encukou commented on Sep 5, 2025

    

    encukou

    on Sep 5, 2025

    Member

    More actions

    See #137469
13. encukou

    closed this as completedin #137469on Dec 3, 2025

Issue actions