Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork33.3k
gh-132661: docs: add a t-string tutorial#137213
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
Uh oh!
There was an error while loading.Please reload this page.
Conversation
davepeck commentedAug 17, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
(Marking as ready so we get some eyes on this. I think there are a lot of directions we can take this content, including simply deciding not to include it in the Python docs whatsoever. Hopefully there'ssomething useful here, though?) |
I'll add this to my to-do list. I have a few reorganisation thoughts after a quick skim, but I want to look at things properly before doing so. Would you mind if I push directly to the branch? GH makes it hard to effectively suggest that kind of change. A |
Not at all; please do! The more eyes and authors the better here, I think. |
| >>> template.values | ||
| ('World',) | ||
| * The:meth:`str.format` method of strings requires more manual |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This followed on fromf-strings, but now it may be confusing, as it makes it seem like this works like the previous (i.e.t-strings with the changes).
| * When greater control is needed,:ref:`template string literals<tut-t-strings>` | ||
| can be useful. T-strings -- which begin with ``t`` or ``T`` -- share the | ||
| same syntax as f-strings but, unlike f-strings, produce a | ||
| :class:`~string.templatelib.Template` instance rather than a simple ``str``. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| :class:`~string.templatelib.Template` instance rather than a simple``str``. | |
| :class:`~string.templatelib.Template` instance rather than a simple:class:`str`. |
| * When greater control is needed,:ref:`template string literals<tut-t-strings>` | ||
| can be useful. T-strings -- which begin with ``t`` or ``T`` -- share the | ||
| same syntax as f-strings but, unlike f-strings, produce a |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This is confusing, since the term:f-strings has not been introduced in the previous point.
| Template String Literals | ||
| ------------------------- | ||
| :ref:`Template string literals<t-strings>` (also called t-strings for short) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| :ref:`Template string literals<t-strings>` (also called t-strings for short) | |
| :ref:`Template string literals<t-strings>` (also called*t-strings* for short) |
| ...name:str | ||
| ... | ||
| Imagine using f-strings in to generate HTML for the ``User``: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| Imagine using f-stringsinto generate HTML for the ``User``: | |
| Imagine using f-strings to generate HTML for the ``User``: |
| defining a more complex ``html()`` function that returns a structured | ||
| representation of the HTML: | ||
| >>>from dataclassesimport dataclass |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This is a very complex example for this stage in the tutorial, many things have not been introduced yet.
Thanks@StanFromIreland -- that is all helpful feedback. Lots of work still to do here to massage this into something usable. |
The proposed doc and its length makes me think that the t-string tutorial should not be in the python tutorial, but in another document. (See logging for example of doc split between tutorial, cookbook, reference) |
A t-string HOWTO seems like a good idea. |
I'll third that. t-strings, as introduced here, are useful if you're writing a library; it's not really about putting data in fancy messages. |
I'm happy to close this and regroup on a future potential tutorial doc. |
Uh oh!
There was an error while loading.Please reload this page.
During thefirst pass at t-string docs, we wrote a potential addition to theFancier Output Formatting section of theInput/Output Tutorial.
It didn't quite feel ready, and maybe wasn't in the right corner of the docs, so we decided to break it out into a separate PR and wrestle it to its final form. :-)
CC@encukou and@AA-Turner -- happy to drop this entirely, or massage it into something better.
See alsoTrey's useful comments on the tutorial.
📚 Documentation preview 📚:https://cpython-previews--137213.org.readthedocs.build/