gh-132661: Document t-strings and `templatelib` #135229

davepeck · 2025-06-06T23:49:17Z

This PR adds documentation for t-strings, including:

Document string.templatelib in the Library reference section
Add new t-string details to lexical-analysis.rst
Add AST nodes to the ast docs
Add BUILD_INTERPOLATION and BUILD_TEMPLATE to the dis docs
Update the PEP 292 section Template strings section of Doc/library/string.rst to clarify that this is unrelated 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 our original list of PEP 750 documentation tasks.

Issue: Implement PEP 750 – Template Strings #132661

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

…nce of `templatelib.Template`.

Doc/reference/lexical_analysis.rst

Doc/library/string.templatelib.rst

davepeck · 2025-06-13T14:35:41Z

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

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

Doc/reference/lexical_analysis.rst

Doc/glossary.rst

davepeck · 2025-07-15T19:15:31Z

Added @AA-Turner's documentation for string.templatelib.convert().

Doc/library/string.templatelib.rst

Co-authored-by: Loïc Simon <loic.pano@gmail.com>

encukou

+1 from me!

hugovk · 2025-07-20T10:29:21Z

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

As release manager, I've given him until the 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.

picnixz

I would adivse against using !class.attr in Sphinx roles as this would also make class 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.

Doc/library/string.templatelib.rst

Doc/tutorial/inputoutput.rst

davepeck · 2025-07-21T18:12:36Z

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!

picnixz

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.

picnixz · 2025-07-21T18:09:36Z

Doc/library/string.templatelib.rst

+
+   .. attribute:: expression
+
+       :returns: The text of a valid Python expression, or an empty string.


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

AA-Turner

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

AA-Turner · 2025-07-22T07:40:49Z

Doc/glossary.rst

@@ -462,7 +462,7 @@ Glossary
      core and with user code.

   f-string


Suggested change

f-string

f-string

f-strings

AA-Turner · 2025-07-22T07:41:08Z

Doc/glossary.rst

@@ -1322,6 +1322,11 @@ Glossary

      See also :term:`borrowed reference`.

+   t-string


Suggested change

t-string

t-string

t-strings

AA-Turner · 2025-07-22T07:43:31Z

Doc/library/ast.rst

+     * 115 (``ord('s')``): ``!s`` string formatting
+     * 114 (``ord('r')``): ``!r`` repr formatting
+     * 97 (``ord('a')``): ``!a`` ASCII formatting


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')``)

AA-Turner · 2025-07-22T07:59:25Z

Doc/library/ast.rst

+.. class:: TemplateStr(values)
+
+   A t-string, comprising a series of :class:`Interpolation` and :class:`Constant`
+   nodes.


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.

AA-Turner · 2025-07-22T08:03:03Z

Doc/library/ast.rst

+   .. versionadded:: 3.14
+
+
+.. class:: Interpolation(value, str, conversion, format_spec)


Suggested change

.. class:: Interpolation(value, str, conversion, format_spec)

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

AA-Turner · 2025-07-22T08:55:04Z

Doc/reference/lexical_analysis.rst

+- Rather than evaluating to a ``str`` object, t-strings evaluate to a
+  :class:`~string.templatelib.Template` object from the


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

AA-Turner · 2025-07-22T08:55:14Z

Doc/reference/lexical_analysis.rst

+  :class:`~string.templatelib.Template` object from the
+  :mod:`string.templatelib` module.
+
+- The :func:`format` protocol is not used. Instead, the format specifier and


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

AA-Turner · 2025-07-22T08:55:27Z

Doc/reference/lexical_analysis.rst

+  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,


Suggested change

- Format specifiers containing nested replacement fields are evaluated eagerly,

* Format specifiers containing nested replacement fields are evaluated eagerly,

AA-Turner · 2025-07-22T08:55:54Z

Doc/reference/lexical_analysis.rst

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


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

AA-Turner · 2025-07-22T08:56:29Z

Doc/reference/lexical_analysis.rst

+  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


Suggested change

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

* When the equals sign ``'='`` is provided in an interpolation expression, the

AA-Turner · 2025-07-22T09:00:07Z

@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

AA-Turner

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

AA-Turner · 2025-07-22T09:05:07Z

Doc/library/string.templatelib.rst

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


Suggested change

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

* :ref:`Template string literal (t-string) syntax <t-strings>`

AA-Turner · 2025-07-22T09:06:00Z

Doc/library/string.templatelib.rst

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


Suggested change

* :pep:`750`

AA-Turner · 2025-07-22T09:19:09Z

Doc/library/string.templatelib.rst

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


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', ''),)

)

AA-Turner · 2025-07-22T09:21:50Z

Doc/library/string.templatelib.rst

+The :class:`!Template` class describes the contents of a template string.
+
+:class:`!Template` instances are immutable: their attributes cannot be
+reassigned.
+


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.

AA-Turner · 2025-07-22T09:26:03Z

Doc/library/string.templatelib.rst

+   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'>


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

AA-Turner · 2025-07-22T09:30:24Z

Doc/library/string.templatelib.rst

+   .. attribute:: values
+       :type: tuple[Any, ...]
+
+       A tuple of all interpolated values in the template.


Suggested change

A tuple of all interpolated values in the template.

A tuple of the values of every interpolation in the template.

AA-Turner · 2025-07-22T09:32:43Z

Doc/library/string.templatelib.rst

+       Iterate over the template, yielding each string and
+       :class:`Interpolation` in order.


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

AA-Turner · 2025-07-22T09:33:46Z

Doc/library/string.templatelib.rst

+   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


As with Template, I think direct construction should be moved to Interpolation.__init__()

AA-Turner · 2025-07-22T09:35:19Z

Doc/library/string.templatelib.rst

+   * ``'s'`` which calls :func:`str` on the value,
+   * ``'r'`` which calls :func:`repr`, and
+   * ``'a'`` which calls :func:`ascii`.


Added the exclamation-mark forms for people doing a Ctrl-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``).

AA-Turner · 2025-07-22T09:36:11Z

Doc/library/string.templatelib.rst

+   Interpolations support pattern matching, allowing you to match against
+   their attributes with the :ref:`match statement <match>`:
+
+   >>> from string.templatelib import 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


This should be moved up into the main body description of Interpolation

hugovk · 2025-07-22T09:44:07Z

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

miss-islington-app · 2025-07-22T09:44:33Z

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

(cherry picked from commit 22c8658) 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 · 2025-07-22T09:44:47Z

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

…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 · 2025-07-22T18:22:32Z

See #137020 for the promised followup.

A

Initial commit.

5a8dbfa

bedevere-app bot added docs Documentation in the Doc dir skip news labels Jun 6, 2025

github-project-automation bot added this to Docs PRs Jun 6, 2025

github-project-automation bot moved this to Todo in Docs PRs Jun 6, 2025

bedevere-app bot mentioned this pull request Jun 6, 2025

Implement PEP 750 – Template Strings #132661

Open

pauleveritt and others added 10 commits June 8, 2025 10:49

Make clear the preceding discussion about t-strings creating an insta…

09a1e9e

…nce of `templatelib.Template`.

Get the import order sorted.

ec44c2b

Correct the Interpolation() calls.

d8904b6

Add documentation for Interpolation.

550aa6d

Convert to use Sphinx modifiers for type, returns, and rtype.

a20e058

Add an entry to the glossary.

1f30739

Find any occurrences of f-strings that should also mention t-strings.

d935dd6

Fix doctests for str.templatelib

1e47362

Start writing the t-strings part of lexical analysis

7b660be

Merge branch 'main' into docs/pep750-first-pass

00a535d

hugovk reviewed Jun 13, 2025

View reviewed changes

davepeck added 3 commits June 17, 2025 17:22

Fix lint issues

fcd74e6

Fix further sphinx warnings

a796f5d

More!

21d337c

brianschubert mentioned this pull request Jun 22, 2025

No documentation of string.templatelib #135804

Closed

davepeck added 3 commits June 26, 2025 13:02

Merge branch 'main' into docs/pep750-first-pass

d043381

Wrap up lexical analysis updates... I think?

9a0a301

Document the new AST nodes (TemplateStr and Interpolation)

f2e5ca4

davepeck mentioned this pull request Jun 26, 2025

Write the official cpython documentation for t-strings t-strings/help#2

Open

11 tasks

First pass at documenting BUILD_TEMPLATE and BUILD_INTERPOLATION

8484b81

encukou reviewed Jun 27, 2025

View reviewed changes

Doc/reference/lexical_analysis.rst Outdated Show resolved Hide resolved

encukou reviewed Jun 27, 2025

View reviewed changes

Doc/glossary.rst Outdated Show resolved Hide resolved

davepeck mentioned this pull request Jun 27, 2025

gh-135676: Lexical analysis: Reword String literals and related sections #135942

Merged

loic-simon reviewed Jul 18, 2025

View reviewed changes

Doc/library/string.templatelib.rst Outdated Show resolved Hide resolved

Update Doc/library/string.templatelib.rst

2da418b

Co-authored-by: Loïc Simon <loic.pano@gmail.com>

encukou approved these changes Jul 20, 2025

View reviewed changes

picnixz self-requested a review July 20, 2025 10:44

picnixz reviewed Jul 20, 2025

View reviewed changes

davepeck added 5 commits July 21, 2025 10:58

Merge branch 'main' into docs/pep750-first-pass

9070840

Revert unrelated change in inputoutput.rst

5af0434

"shallow immutable" -> "immutable"

437320d

Use :type:, not :rtype:, for attributes.

d69d8e0

'is always' -> 'always has'

ae6f072

Merge branch 'main' into docs/pep750-first-pass

6446762

picnixz approved these changes Jul 21, 2025

View reviewed changes

AA-Turner reviewed Jul 22, 2025

View reviewed changes

hugovk merged commit 22c8658 into python:main Jul 22, 2025
25 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Jul 22, 2025

bedevere-app bot removed the awaiting merge label Jul 22, 2025

hugovk added the needs backport to 3.14 bugs and security fixes label Jul 22, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jul 22, 2025

AA-Turner mentioned this pull request Jul 22, 2025

gh-132661: PEP 750 documentation: second pass #137020

Open


		.. attribute:: expression

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

		@@ -462,7 +462,7 @@ Glossary
		core and with user code.

		f-string

		@@ -1322,6 +1322,11 @@ Glossary

		See also :term:`borrowed reference`.

		t-string

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

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

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

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

		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
	* When the equals sign ``'='`` is provided in an interpolation expression, the

	* :ref:`T-string literal syntax <t-strings>`
	* :ref:`Template string literal (t-string) syntax <t-strings>`


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

-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', ''),)
+   )

	A tuple of all interpolated values in the template.
	A tuple of the values of every interpolation in the template.

		Iterate over the template, yielding each string and
		:class:`Interpolation` in order.

Uh oh!

gh-132661: Document t-strings and templatelib #135229

gh-132661: Document t-strings and templatelib #135229

Uh oh!

Conversation

davepeck commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davepeck commented Jun 13, 2025

Uh oh!

Uh oh!

Uh oh!

davepeck commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

encukou left a comment

Choose a reason for hiding this comment

Uh oh!

hugovk commented Jul 20, 2025

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davepeck commented Jul 21, 2025

Uh oh!

picnixz left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AA-Turner commented Jul 22, 2025

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

gh-132661: Document t-strings and `templatelib` #135229

gh-132661: Document t-strings and `templatelib` #135229

davepeck commented Jun 6, 2025 •

edited

Loading

davepeck commented Jul 15, 2025 •

edited

Loading

picnixz left a comment •

edited

Loading