Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

gh-132661: Document t-strings andtemplatelib#135229

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

Merged
hugovk merged 57 commits intopython:mainfromt-strings:docs/pep750-first-pass
Jul 22, 2025

Conversation

@davepeck
Copy link
Contributor

@davepeckdavepeck commentedJun 6, 2025•
edited
Loading

This PR adds documentation for t-strings, including:

  • Documentstring.templatelib in theLibrary reference section
  • Add new t-string details tolexical-analysis.rst
  • Add AST nodes totheast docs
  • AddBUILD_INTERPOLATION andBUILD_TEMPLATE to thedis docs
  • Update the PEP 292 sectionTemplate strings section ofDoc/library/string.rst to clarify that this isunrelated to t-strings
  • Add a t-strings section to "fancier input/output formatting", after the f-strings section
  • Glossary

We also have an issue tracking ouroriginal list of PEP 750 documentation tasks.

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

@davepeck
Copy link
ContributorAuthor

@hugovk Thank you for the review and the helpful early feedback! Useful to know about linking.

(FWIW this isvery early stage still, so I expect plenty more linting and other issues that we'll eventually resolve.)

hugovk reacted with thumbs up emoji

@hugovk
Copy link
Member

At EuroPython sprints,@AA-Turner says he still wants to review this.

As release manager, I've given him untilthe first release candidate on Tuesday when I'll merge this. We can always make further updates, but let's at least have something for RC1.

davepeck and treyhunner reacted with thumbs up emoji

@picnixzpicnixz self-requested a reviewJuly 20, 2025 10:44
Copy link
Member

@picnixzpicnixz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I would adivse against using!class.attr in Sphinx roles as this would also makeclass being rendered, and instead, I suggest using regular double-backticks instead or use attr +~, although this would create a link that we may not want it.

On Sphinx' side, I think we should really do something for supporting!~ because it becomes annoying to lose semantics.

davepeck reacted with thumbs up emoji
@davepeck
Copy link
ContributorAuthor

Thanks@picnixz for the feedback! Think I took care of all your suggestions.

On Sphinx' side, I think we should really do something for supporting!~ because it becomes annoying to lose semantics.

That would be really nice!

Copy link
Member

@picnixzpicnixz left a comment•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

As a sphinx maintainer I'm happy to see that directives are used but I fear that it could make the text a bit too "heavy to read". My main concern is that the theme we use actually creates lots of boxes and only a few online pages relies on directives, and prefer indicating the parameter type or the attribute type in the text directly (for instance for "expression", we would rather say "The text of a valid Python expression as a str, possibly empty".

I won't block this PR because of this choice as it's an entirely new page but in the future we may want to remove parameter boxes from the documentation.

If we don't have time until the RC release to fix the links/refs/inline code, we can do it later. For the content itself, I'm mostly good.


..attribute::expression

:returns: The text of a valid Python expression, or an empty string.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

No need for:returns: You can write the attribute directive body the same way you did for Template.interpolations for instance.

Copy link
Member

@AA-TurnerAA-Turner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Sorry for the delay, I abandoned my review and started over as various things had gotten out of date. I'll apply the simple fixes manually for time.

A

A module written in C or C++, using Python's C API to interact with the
core and with user code.

f-string
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
f-string
f-string
f-strings


See also:term:`borrowed reference`.

t-string
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
t-string
t-string
t-strings

Comment on lines +292 to +294
* 115 (``ord('s')``): ``!s`` string formatting
* 114 (``ord('r')``): ``!r`` repr formatting
* 97 (``ord('a')``): ``!a``ASCII formatting
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
*115(``ord('s')``): ``!s`` string formatting
* 114 (``ord('r')``): ``!r`` repr formatting
*97(``ord('a')``): ``!a`` ASCII formatting
*97: ``!a``:func:`ASCII <ascii>` formatting(``ord('a')``)
* 114: ``!r``:func:`repr` formatting (``ord('r')``)
*115: ``!s``:func:`string <str>` formatting(``ord('s')``)

Comment on lines +328 to +331
..class::TemplateStr(values)

A t-string, comprising a series of:class:`Interpolation` and:class:`Constant`
nodes.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Add a note on AST node ordering

Suggested change
..class::TemplateStr(values)
A t-string, comprising a series of:class:`Interpolation` and:class:`Constant`
nodes.
..class::TemplateStr(values, /)
Node representing a template string literal, comprising a series of
:class:`Interpolation` and:class:`Constant` nodes.
These nodes may be any order, and do not need to be interleaved.

..versionadded::3.14


..class::Interpolation(value, str, conversion, format_spec)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
..class::Interpolation(value, str, conversion, format_spec)
..class::Interpolation(value, str, conversion, format_spec=None)

Comment on lines +929 to +930
- Rather than evaluating to a ``str`` object, t-strings evaluate to a
:class:`~string.templatelib.Template` object from the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
- Rather than evaluating to a ``str`` object,t-strings evaluate to a
:class:`~string.templatelib.Template` object from the
* Rather than evaluating to a ``str`` object,template string literals evaluate
to a:class:`~string.templatelib.Template` object from the

:class:`~string.templatelib.Template` object from the
:mod:`string.templatelib` module.

- The:func:`format` protocol is not used. Instead, the format specifier and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
- The:func:`format` protocol is not used. Instead, the format specifier and
* The:func:`format` protocol is not used. Instead, the format specifier and

processes the resulting:class:`~string.templatelib.Template` object to
decide how to handle format specifiers and conversions.

- Format specifiers containing nested replacement fields are evaluated eagerly,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
- Format specifiers containing nested replacement fields are evaluated eagerly,
* Format specifiers containing nested replacement fields are evaluated eagerly,

Comment on lines +943 to +944
attribute of the resulting:class:`!Interpolation` object; if ``precision``
is (for example) ``2``, the resulting format specifier will be ``'.2f'``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
attribute of the resulting:class:`!Interpolation` object; if ``precision``
is (for example) ``2``, the resulting format specifier will be ``'.2f'``.
attribute of the resulting:class:`!Interpolation` object.
For example, if ``precision`` is ``2``, the resulting format specifier
will be ``'.2f'``.

attribute of the resulting:class:`!Interpolation` object; if ``precision``
is (for example) ``2``, the resulting format specifier will be ``'.2f'``.

- When the equal sign ``'='`` is provided in an interpolation expression, the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
- When theequal sign ``'='`` is provided in an interpolation expression, the
* When theequals sign ``'='`` is provided in an interpolation expression, the

@AA-Turner
Copy link
Member

@davepeck@lysnikolaou this PR is from an organisation fork (@t-strings), so we can't apply suggestions or push commits. Please would you be able to do so? Hugo wants to get this PR in before starting RC1 later today.

A

Copy link
Member

@AA-TurnerAA-Turner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Part 2 (briefer as we can't apply suggestions)

..seealso::

*:ref:`Format strings<f-strings>`
*:ref:`T-string literal syntax<t-strings>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
*:ref:`T-string literal syntax<t-strings>`
*:ref:`Templatestring literal (t-string) syntax<t-strings>`


*:ref:`Format strings<f-strings>`
*:ref:`T-string literal syntax<t-strings>`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
*:pep:`750`

Comment on lines +24 to +30
Template strings are a formatting mechanism that allows for deep control over
how strings are processed. You can create templates using
:ref:`t-string literal syntax<t-strings>`, which is identical to
:ref:`f-string syntax<f-strings>` but uses a ``t`` instead of an ``f``.
While f-strings evaluate to ``str``, t-strings create a:class:`Template`
instance that gives you access to the static and interpolated (in curly braces)
parts of a string *before* they are combined.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
Template strings are a formatting mechanism that allows for deep control over
how strings are processed. You can create templates using
:ref:`t-string literal syntax<t-strings>`, which is identical to
:ref:`f-string syntax<f-strings>` but uses a ``t`` instead of an ``f``.
While f-strings evaluate to ``str``, t-strings create a:class:`Template`
instance that gives you access to the static and interpolated (in curly braces)
parts of a string *before* they are combined.
Template strings are a mechanism for custom string processing.
They have the full flexibility of Python's:ref:`f-strings`,
but return a:class:`Template` instance that gives access
to the static and interpolated (in curly braces) parts of a string
*before* they are combined.
To write a t-string, use a ``'t'`` prefix instead of an ``'f'``, like so:
..code-block::pycon
>>>pi=3.14
>>>t't-strings are new in Python{pi!s}!'
Template(
strings=('t-strings are new in Python ', '!'),
interpolations=(Interpolation(3.14, 'pi', 's', ''),)
)

Comment on lines +38 to +42
The:class:`!Template` class describes the contents of a template string.

:class:`!Template` instances are immutable: their attributes cannot be
reassigned.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
The:class:`!Template` class describes the contents of a template string.
:class:`!Template` instances are immutable: their attributes cannot be
reassigned.
The:class:`!Template` class describes the contents of a template string.
It is immutable, meaning that attributes of a template cannot be reassigned.

Comment on lines +45 to +57
Create a new:class:`!Template` object.

:param args: A mix of strings and:class:`Interpolation` instances in any order.
:type args: str | Interpolation

The most common way to create a:class:`!Template` instance is to use the
:ref:`t-string literal syntax<t-strings>`. This syntax is identical to that of
:ref:`f-strings<f-strings>` except that it uses a ``t`` instead of an ``f``:

>>>name="World"
>>>template= t"Hello{name}!"
>>>type(template)
<class 'string.templatelib.Template'>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I think this should be moved later; most users won't need to createTemplate objects by calling the class, but will need to know what the class is for and does. Perhaps you could separately documentTemplate.__init__()?

..attribute::values
:type: tuple[Any, ...]

A tuple of all interpolated values in the template.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change
A tuple ofall interpolatedvalues in the template.
A tuple ofthevalues of every interpolation in the template.

Comment on lines +162 to +163
Iterate over the template, yielding each string and
:class:`Interpolation` in order.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

"in order" here I think could do with more exposition, or reference to the "proper" order of aTemplate

Comment on lines +205 to +217
Create a new:class:`!Interpolation` object.

:param value: The evaluated, in-scope result of the interpolation.
:type value: object

:param expression: The text of a valid Python expression, or an empty string.
:type expression: str

:param conversion: The optional:ref:`conversion<formatstrings>` to be used, one of r, s, and a.
:type conversion: ``Literal["a", "r", "s"] | None``

:param format_spec: An optional, arbitrary string used as the:ref:`format specification<formatspec>` to present the value.
:type format_spec: str
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

As withTemplate, I think direct construction should be moved toInterpolation.__init__()

Comment on lines +309 to +311
* ``'s'`` which calls:func:`str` on the value,
* ``'r'`` which calls:func:`repr`, and
* ``'a'`` which calls:func:`ascii`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Added the exclamation-mark forms for people doing aCtrl-F search

Suggested change
* ``'s'`` which calls:func:`str` on the value,
* ``'r'`` which calls:func:`repr`, and
* ``'a'`` which calls:func:`ascii`.
* ``'s'`` which calls:func:`str` on the value (like ``!s``),
* ``'r'`` which calls:func:`repr` (like ``!r``), and
* ``'a'`` which calls:func:`ascii` (like ``!a``).

blaisep reacted with hooray emoji
Comment on lines +286 to +295
Interpolations support pattern matching, allowing you to match against
their attributes with the:ref:`match statement<match>`:

>>>from string.templatelibimport Interpolation
>>>interpolation= Interpolation(3.0,"1 + 2",None,".2f")
>>>match interpolation:
...case Interpolation(value, expression, conversion, format_spec):
...print(value, expression, conversion, format_spec)
...
3.0 1 + 2 None .2f
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This should be moved up into the main body description ofInterpolation

@hugovk
Copy link
Member

Let's merge and add the updates in a followup. Thanks all! 🫖🧵📚🚀

davepeck reacted with hooray emoji

@hugovkhugovk merged commit22c8658 intopython:mainJul 22, 2025
25 checks passed
@github-project-automationgithub-project-automationbot moved this fromTodo toDone inDocs PRsJul 22, 2025
@hugovkhugovk added the needs backport to 3.14bugs and security fixes labelJul 22, 2025
@miss-islington-app
Copy link

Thanks@davepeck for the PR, and@hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull requestJul 22, 2025
(cherry picked from commit22c8658)Co-authored-by: Dave Peck <davepeck@gmail.com>Co-authored-by: Petr Viktorin <encukou@gmail.com>Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>Co-authored-by: Loïc Simon <loic.pano@gmail.com>Co-authored-by: pauleveritt <pauleveritt@me.com>
@bedevere-app
Copy link

GH-136974 is a backport of this pull request to the3.14 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.14bugs and security fixes labelJul 22, 2025
hugovk added a commit that referenced this pull requestJul 22, 2025
…136974)Co-authored-by: Dave Peck <davepeck@gmail.com>Co-authored-by: Petr Viktorin <encukou@gmail.com>Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>Co-authored-by: Loïc Simon <loic.pano@gmail.com>Co-authored-by: pauleveritt <pauleveritt@me.com>Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com>
@AA-Turner
Copy link
Member

See#137020 for the promised followup.

A

davepeck and encukou reacted with hooray emojihugovk reacted with rocket emoji

taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull requestAug 4, 2025
Co-authored-by: Petr Viktorin <encukou@gmail.com>Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>Co-authored-by: Loïc Simon <loic.pano@gmail.com>Co-authored-by: pauleveritt <pauleveritt@me.com>
Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull requestAug 19, 2025
Co-authored-by: Petr Viktorin <encukou@gmail.com>Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>Co-authored-by: Loïc Simon <loic.pano@gmail.com>Co-authored-by: pauleveritt <pauleveritt@me.com>
kumaraditya303 pushed a commit to miss-islington/cpython that referenced this pull requestSep 9, 2025
…H-135229) (python#136974)Co-authored-by: Dave Peck <davepeck@gmail.com>Co-authored-by: Petr Viktorin <encukou@gmail.com>Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>Co-authored-by: Loïc Simon <loic.pano@gmail.com>Co-authored-by: pauleveritt <pauleveritt@me.com>Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com>
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment

Reviewers

@hugovkhugovkhugovk approved these changes

@AA-TurnerAA-TurnerAA-Turner left review comments

@encukouencukouencukou approved these changes

@picnixzpicnixzpicnixz approved these changes

@lysnikolaoulysnikolaouAwaiting requested review from lysnikolaoulysnikolaou is a code owner

@willingcwillingcAwaiting requested review from willingcwillingc is a code owner

+2 more reviewers

@koxudaxikoxudaxikoxudaxi left review comments

@loic-simonloic-simonloic-simon left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

docsDocumentation in the Doc dirskip news

Projects

Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

10 participants

@davepeck@treyhunner@blaisep@encukou@hugovk@AA-Turner@koxudaxi@picnixz@loic-simon@pauleveritt
[8]ページ先頭
©2009-2025 Movatter.jp