gh-132661: docs: add a t-string tutorial #137213
Conversation
|
(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's something 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. |
| ('Hello ', '!') | ||
| >>> template.values | ||
| ('World',) | ||
|
|
||
| * The :meth:`str.format` method of strings requires more manual |
There was a problem hiding this comment.
This followed on from f-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.
| :class:`~string.templatelib.Template` instance rather than a simple ``str``. | |
| :class:`~string.templatelib.Template` instance rather than a simple :class:`str`. |
| @@ -34,6 +34,22 @@ printing space-separated values. There are several ways to format output. | |||
| >>> f'Results of the {year} {event}' | |||
| 'Results of the 2016 Referendum' | |||
|
|
|||
| * 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.
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.
| :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.
| Imagine using f-strings in to 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 dataclasses import dataclass |
There was a problem hiding this comment.
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. |
During the first pass at t-string docs, we wrote a potential addition to the Fancier Output Formatting section of the Input/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 also Trey's useful comments on the tutorial.
📚 Documentation preview 📚: https://cpython-previews--137213.org.readthedocs.build/