gh-132661: docs: add a t-string tutorial#137213
gh-132661: docs: add a t-string tutorial#137213davepeck wants to merge 1 commit intopython:mainpython/cpython:mainfrom t-strings:docs/pep750-tutorialt-strings/cpython:docs/pep750-tutorialCopy head branch name to clipboard
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. |
| >>> 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`. |
|
|
||
| * 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. |
|
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. |
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/