Skip to content

gh-132661: Document t-strings and templatelib #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 our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 11 commits into
base: main
Choose a base branch
from

Conversation

davepeck
Copy link
Contributor

@davepeck davepeck commented Jun 6, 2025

[DRAFT] This has only just begun and is very much a work in progress; putting up a draft PR now for visibility.

We're keeping a TODO list of PEP 750 documentation tasks. There's lots to do.


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

syntax and evaluation rules as `formatted string literals <f-strings>`_, with
the following differences:

- Rather than evaluating to a `str` object, t-strings evaluate to a
Copy link
Member

Choose a reason for hiding this comment

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

Lint fix, either use double backticks (this is RST not MD):

Suggested change
- Rather than evaluating to a `str` object, t-strings evaluate to a
- Rather than evaluating to a ``str`` object, t-strings evaluate to a

Or create link:

Suggested change
- Rather than evaluating to a `str` object, t-strings evaluate to a
- Rather than evaluating to a :class:`str` object, t-strings evaluate to a

Comment on lines +934 to +937
the expressions are evaluated and a new `Interpolation` object (also from the
:mod:`string.templatelib` module) is created, which contains the evaluated
value of the expression. That `Interpolation` object is found in the containing
`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
the expressions are evaluated and a new `Interpolation` object (also from the
:mod:`string.templatelib` module) is created, which contains the evaluated
value of the expression. That `Interpolation` object is found in the containing
`Template`.
the expressions are evaluated and a new :class:`~string.templatelib.Interpolation` object (also from the
:mod:`string.templatelib` module) is created, which contains the evaluated
value of the expression. That :class:`~string.templatelib.Interpolation` object is found in the containing
:class:`~string.templatelib.Template`.

the following differences:

- Rather than evaluating to a `str` object, t-strings evaluate to a
`Template` object from the :mod:`string.templatelib` module.
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` object from the :mod:`string.templatelib` module.
:class:`~string.templatelib.Template` object from the :mod:`string.templatelib` module.

Template
--------

The :class:`Template` class describes the contents of a template string.
Copy link
Member

Choose a reason for hiding this comment

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

We try to avoid creating too many hyperlinks, see:
https://devguide.python.org/documentation/style-guide/#links

So we don't need to link this one back to this same section. We can prevent Sphinx from linking like this, but it still applies the other formatting:

Suggested change
The :class:`Template` class describes the contents of a template string.
The :class:`!Template` class describes the contents of a template string.


The :class:`Template` class describes the contents of a template string.

The most common way to create a new :class:`Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`Template` that can be used to format strings:
Copy link
Member

Choose a reason for hiding this comment

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

We try to avoid creating too many hyperlinks, see:
https://devguide.python.org/documentation/style-guide/#links

So we don't need to link this repeated mentions. We can prevent Sphinx from linking like this, but it still applies the other formatting:

Suggested change
The most common way to create a new :class:`Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`Template` that can be used to format strings:
The most common way to create a new :class:`!Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`!Template` that can be used to format strings:

Also, please try and wrap at ~80 chars.

https://devguide.python.org/documentation/markup/#use-of-whitespace

>>> print(list(greeting))
['Hello ', Interpolation('World', 'name', None, ''), '!']

It is also possible to create a :class:`Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances:
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
It is also possible to create a :class:`Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances:
It is also possible to create a :class:`!Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances:

Comment on lines +43 to +48
Create a new :class:`Template` object.

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

If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`Template` with a single final string:
Copy link
Member

Choose a reason for hiding this comment

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

Similarly, we try and avoid linking back to the same unit.

Suggested change
Create a new :class:`Template` object.
:param args: A mix of strings and :class:`Interpolation` instances in any order.
:type args: str | Interpolation
If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`Template` with a single final string:
Create a new :class:`!Template` object.
:param args: A mix of strings and :class:`Interpolation` instances in any order.
:type args: str | Interpolation
If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`!Template` with a single final string:


.. class:: Interpolation(*args)

Create a new :class:`Interpolation` object.
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
Create a new :class:`Interpolation` object.
Create a new :class:`!Interpolation` object.

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

The :class:`Interpolation` type represents an expression inside a template string. It is shallow immutable -- its 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:`Interpolation` type represents an expression inside a template string. It is shallow immutable -- its attributes cannot be reassigned.
The :class:`!Interpolation` type represents an expression inside a template string. It is shallow immutable -- its attributes cannot be reassigned.

@davepeck
Copy link
Contributor Author

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

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

Successfully merging this pull request may close these issues.

3 participants