gh-135676: Reword the f-string (and t-string) section#137469

encukou · 2025-08-06T15:20:39Z

Continuing from #135942, this tackles the f-string section.

Much of the information was duplicated in stdtypes.rst; this PR keeps lexical/syntactical details in Lexical Analysis and the evaluation & runtime behaviour in Standard types, with cross-references between the two.
Since the t-string section only listed differences from f-strings, and the grammar for the two is equivalent, that section was moved to Standard types almost entirely.

Issue: Reword the Lexical Analysis chapter of the docs #135676

📚 Documentation preview 📚: https://cpython-previews--137469.org.readthedocs.build/

Co-authored-by: Blaise Pabon <blaise@gmail.com>

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Blaise Pabon <blaise@gmail.com>

Doc/library/stdtypes.rst

bedevere-app · 2025-10-08T06:12:11Z

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

And if you don't make the requested changes, you will be put in the comfy chair!

encukou · 2025-10-08T07:54:11Z

The question is: Does this PR bring the docs closer to the desired state? Would you be OK with basing your PR on this rather than the status quo?

I did try to move runtime stuff to stdtypes and lexical stuff to lexical_analysis, but yeah, this can always be improved.

ericvsmith · 2025-10-08T10:40:38Z

This PR addresses #125496. I've closed that issue in preference to this one.

encukou · 2025-10-29T15:11:15Z

@AA-Turner: Would it make sense for you to work on top of this PR?

encukou · 2025-11-26T15:13:19Z

I plan to to merge this next week if there are no objections.

willingc · 2025-11-26T21:49:08Z

Doc/library/stdtypes.rst

- >>> nationality ='Spanish'
- >>> f'The {nationality} Inquisition!'
-'The Spanish Inquisition!'
+Whitespace before, inside and after the expression, as well as whitespace


Perhaps highlight a bit. I didn't realize that the whitespace was significant before and after within the{}.

Do you have a suggestion on how to highlight this?
FWIW, I don't think this is a very important detail, since it only affects formatting of debug output.

Let's not have the perfect be the enemy of the good. Follow-up PRs are always welcome.

miss-islington-app · 2025-12-03T15:14:57Z

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

…-137469) Much of the information was duplicated in stdtypes.rst; this PR keeps lexical/syntactical details in Lexical Analysis and the evaluation & runtime behaviour in Standard types, with cross-references between the two. Since the t-string section only listed differences from f-strings, and the grammar for the two is equivalent, that section was moved to Standard types almost entirely. (cherry picked from commit aea5531) 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: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

bedevere-app · 2025-12-03T15:15:17Z

GH-142227 is a backport of this pull request to the 3.14 branch.

miss-islington-app · 2025-12-03T15:15:34Z

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

…-137469) Much of the information was duplicated in stdtypes.rst; this PR keeps lexical/syntactical details in Lexical Analysis and the evaluation & runtime behaviour in Standard types, with cross-references between the two. Since the t-string section only listed differences from f-strings, and the grammar for the two is equivalent, that section was moved to Standard types almost entirely. (cherry picked from commit aea5531) 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: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

miss-islington-app · 2025-12-03T15:16:07Z

Sorry @encukou, I had trouble completing the backport.
Please retry by removing and re-adding the "needs backport to 3.14" label.
Please backport backport using cherry_picker on the command line.

cherry_picker aea5531583aaa8bfdf3ebca914e9c694617c3489 3.14

StanFromIreland · 2025-12-03T16:16:03Z

The fail must have due to the GH outage I heard about in the Discord, it successfully cherry-picked but failed to add the comment.

…ythonGH-137469) Much of the information was duplicated in stdtypes.rst; this PR keeps lexical/syntactical details in Lexical Analysis and the evaluation & runtime behaviour in Standard types, with cross-references between the two. Since the t-string section only listed differences from f-strings, and the grammar for the two is equivalent, that section was moved to Standard types almost entirely. (cherry picked from commit aea5531) 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: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

StanFromIreland · 2025-12-03T16:17:42Z

GH-142227 is a backport of this pull request to the 3.14 branch.

…) (GH-142227) Much of the information was duplicated in stdtypes.rst; this PR keeps lexical/syntactical details in Lexical Analysis and the evaluation & runtime behaviour in Standard types, with cross-references between the two. Since the t-string section only listed differences from f-strings, and the grammar for the two is equivalent, that section was moved to Standard types almost entirely. (cherry picked from commit aea5531) 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: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

…-137469) Much of the information was duplicated in stdtypes.rst; this PR keeps lexical/syntactical details in Lexical Analysis and the evaluation & runtime behaviour in Standard types, with cross-references between the two. Since the t-string section only listed differences from f-strings, and the grammar for the two is equivalent, that section was moved to Standard types almost entirely. Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

encukouand others added 18 commits June 25, 2025 16:27

WIP: String literals
d4381aa
Co-authored-by: Blaise Pabon <blaise@gmail.com>

Use correct Pygments lexer for plain text
80ad85c

WIP
e44fa66

More WIP
86bf94b

Byte strings, raw strings; f-string stub
faf05a1

Remove outdated comment
687fe58

Fix ReST errors
9f9d29c

TMP
1e0c84a

Continue with f-strings
e7b57b5

Merge in the main branch
3733e0c

Work on the f-string semantics
d593940

Work on f-strings
0d8a917

Merge in the main branch
366ecfc

Details & start on the formal grammar
5fdb129
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Blaise Pabon <blaise@gmail.com>

Improve text on whitespace in f-string debug expressions
e88843c

Merge in the main branch
394f835

Comment on the funkiness of the t-string grammar
f2db8f9

Adjust t-string docs: move evaluation rules out, add a note on grammar
6468a97

encukou requested review from AA-Turner and willingc as code owners August 6, 2025 15:20

bedevere-appbot added awaiting core review docs Documentation in the Doc dir skip news labels Aug 6, 2025

github-project-automationbot added this to Docs PRs Aug 6, 2025

github-project-automationbot moved this to Todo in Docs PRs Aug 6, 2025

bedevere-appbot mentioned this pull request Aug 6, 2025
Reword the Lexical Analysis chapter of the docs #135676
Open

StanFromIreland reviewed Aug 6, 2025
View reviewed changes

Doc/library/stdtypes.rst Outdated Show resolvedHide resolved

StanFromIreland reviewed Aug 6, 2025
View reviewed changes

Doc/library/stdtypes.rst Outdated Show resolvedHide resolved
Doc/library/stdtypes.rstShow resolvedHide resolved

encukou mentioned this pull request Aug 12, 2025
f-string documentation not fully accurate #81997
Closed

StanFromIreland linked an issue Aug 12, 2025 that may be closed by this pull request
f-string documentation not fully accurate #81997
Closed

bedevere-appbot added awaiting changes and removed awaiting core review labels Oct 8, 2025

willingc reviewed Nov 26, 2025
View reviewed changes

bedevere-appbot added awaiting review and removed awaiting changes labels Dec 3, 2025

Merge branch 'main' into lex-analysis-fstrings
ebe2a6b

encukou merged commit aea5531 into python:mainDec 3, 2025
28 checks passed

github-project-automationbot moved this from Todo to Done in Docs PRs Dec 3, 2025

bedevere-appbot removed the awaiting review label Dec 3, 2025

bedevere-appbot removed the needs backport to 3.14 bugs and security fixes label Dec 3, 2025

encukou added the needs backport to 3.14 bugs and security fixes label Dec 3, 2025

miss-islington-appbot assigned encukou Dec 3, 2025

StanFromIreland removed the needs backport to 3.14 bugs and security fixes label Dec 3, 2025

Uh oh!

gh-135676: Reword the f-string (and t-string) section#137469

gh-135676: Reword the f-string (and t-string) section #137469

Uh oh!

Conversation

encukou commented Aug 6, 2025• edited by github-actions botLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-appbot commented Oct 8, 2025

Uh oh!

encukou commented Oct 8, 2025

Uh oh!

ericvsmith commented Oct 8, 2025

Uh oh!

encukou commented Oct 29, 2025

Uh oh!

encukou commented Nov 26, 2025

Uh oh!

willingcNov 26, 2025

Choose a reason for hiding this comment

Uh oh!

encukouNov 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-appbot commented Dec 3, 2025

Uh oh!

bedevere-appbot commented Dec 3, 2025

Uh oh!

miss-islington-appbot commented Dec 3, 2025

Uh oh!

miss-islington-appbot commented Dec 3, 2025

Uh oh!

StanFromIreland commented Dec 3, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland commented Dec 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

encukou commented Aug 6, 2025•
edited by github-actions bot
Loading

StanFromIreland commented Dec 3, 2025•
edited
Loading