Skip to content

Commit c59a60b

Browse files
miss-islingtondavepeckencukouhugovkloic-simon
authored
[3.14] gh-132661: Document t-strings and templatelib (GH-135229) (#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>
1 parent d118bc0 commit c59a60b

File tree

10 files changed

+488
-23
lines changed

10 files changed

+488
-23
lines changed

‎Doc/glossary.rst

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -462,7 +462,7 @@ Glossary
462462
core and with user code.
463463

464464
f-string
465-
String literals prefixed with ``'f'`` or ``'F'`` are commonly called
465+
String literals prefixed with ``f`` or ``F`` are commonly called
466466
"f-strings" which is short for
467467
:ref:`formatted string literals <f-strings>`. See also :pep:`498`.
468468

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

13231323
See also :term:`borrowed reference`.
13241324

1325+
t-string
1326+
String literals prefixed with ``t`` or ``T`` are commonly called
1327+
"t-strings" which is short for
1328+
:ref:`template string literals <t-strings>`.
1329+
13251330
text encoding
13261331
A string in Python is a sequence of Unicode code points (in range
13271332
``U+0000``--``U+10FFFF``). To store or transfer a string, it needs to be

‎Doc/library/ast.rst

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -290,9 +290,9 @@ Literals
290290
* ``conversion`` is an integer:
291291

292292
* -1: no formatting
293-
* 115: ``!s`` string formatting
294-
* 114: ``!r`` repr formatting
295-
* 97: ``!a`` ascii formatting
293+
* 115 (``ord('s')``): ``!s`` string formatting
294+
* 114 (``ord('r')``): ``!r`` repr formatting
295+
* 97 (``ord('a')``): ``!a`` ASCII formatting
296296

297297
* ``format_spec`` is a :class:`JoinedStr` node representing the formatting
298298
of the value, or ``None`` if no format was specified. Both
@@ -326,6 +326,54 @@ Literals
326326
Constant(value='.3')]))]))
327327

328328

329+
.. class:: TemplateStr(values)
330+
331+
A t-string, comprising a series of :class:`Interpolation` and :class:`Constant`
332+
nodes.
333+
334+
.. doctest::
335+
336+
>>> print(ast.dump(ast.parse('t"{name} finished {place:ordinal}"', mode='eval'), indent=4))
337+
Expression(
338+
body=TemplateStr(
339+
values=[
340+
Interpolation(
341+
value=Name(id='name', ctx=Load()),
342+
str='name',
343+
conversion=-1),
344+
Constant(value=' finished '),
345+
Interpolation(
346+
value=Name(id='place', ctx=Load()),
347+
str='place',
348+
conversion=-1,
349+
format_spec=JoinedStr(
350+
values=[
351+
Constant(value='ordinal')]))]))
352+
353+
.. versionadded:: 3.14
354+
355+
356+
.. class:: Interpolation(value, str, conversion, format_spec)
357+
358+
Node representing a single interpolation field in a t-string.
359+
360+
* ``value`` is any expression node (such as a literal, a variable, or a
361+
function call).
362+
* ``str`` is a constant containing the text of the interpolation expression.
363+
* ``conversion`` is an integer:
364+
365+
* -1: no conversion
366+
* 115: ``!s`` string conversion
367+
* 114: ``!r`` repr conversion
368+
* 97: ``!a`` ascii conversion
369+
370+
* ``format_spec`` is a :class:`JoinedStr` node representing the formatting
371+
of the value, or ``None`` if no format was specified. Both
372+
``conversion`` and ``format_spec`` can be set at the same time.
373+
374+
.. versionadded:: 3.14
375+
376+
329377
.. class:: List(elts, ctx)
330378
Tuple(elts, ctx)
331379

‎Doc/library/dis.rst

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1120,6 +1120,48 @@ iterations of the loop.
11201120
.. versionadded:: 3.12
11211121

11221122

1123+
.. opcode:: BUILD_TEMPLATE
1124+
1125+
Constructs a new :class:`~string.templatelib.Template` from a tuple
1126+
of strings and a tuple of interpolations and pushes the resulting instance
1127+
onto the stack::
1128+
1129+
interpolations = STACK.pop()
1130+
strings = STACK.pop()
1131+
STACK.append(_build_template(strings, interpolations))
1132+
1133+
.. versionadded:: 3.14
1134+
1135+
1136+
.. opcode:: BUILD_INTERPOLATION (format)
1137+
1138+
Constructs a new :class:`~string.templatelib.Interpolation` from a
1139+
value and its source expression and pushes the resulting instance onto the
1140+
stack.
1141+
1142+
If no conversion or format specification is present, ``format`` is set to
1143+
``2``.
1144+
1145+
If the low bit of ``format`` is set, it indicates that the interpolation
1146+
contains a format specification.
1147+
1148+
If ``format >> 2`` is non-zero, it indicates that the interpolation
1149+
contains a conversion. The value of ``format >> 2`` is the conversion type
1150+
(``0`` for no conversion, ``1`` for ``!s``, ``2`` for ``!r``, and
1151+
``3`` for ``!a``)::
1152+
1153+
conversion = format >> 2
1154+
if format & 1:
1155+
format_spec = STACK.pop()
1156+
else:
1157+
format_spec = None
1158+
expression = STACK.pop()
1159+
value = STACK.pop()
1160+
STACK.append(_build_interpolation(value, expression, conversion, format_spec))
1161+
1162+
.. versionadded:: 3.14
1163+
1164+
11231165
.. opcode:: BUILD_TUPLE (count)
11241166

11251167
Creates a tuple consuming *count* items from the stack, and pushes the

‎Doc/library/stdtypes.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2675,9 +2675,9 @@ For example:
26752675
lead to a number of common errors (such as failing to display tuples and
26762676
dictionaries correctly). Using the newer :ref:`formatted string literals
26772677
<f-strings>`, the :meth:`str.format` interface, or :ref:`template strings
2678-
<template-strings>` may help avoid these errors. Each of these
2679-
alternatives provides their own trade-offs and benefits of simplicity,
2680-
flexibility, and/or extensibility.
2678+
($-strings) <template-strings-pep292>` may help avoid these errors.
2679+
Each of these alternatives provides their own trade-offs and benefits of
2680+
simplicity, flexibility, and/or extensibility.
26812681

26822682
String objects have one unique built-in operation: the ``%`` operator (modulo).
26832683
This is also known as the string *formatting* or *interpolation* operator.

‎Doc/library/string.rst

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -198,8 +198,9 @@ Format String Syntax
198198
The :meth:`str.format` method and the :class:`Formatter` class share the same
199199
syntax for format strings (although in the case of :class:`Formatter`,
200200
subclasses can define their own format string syntax). The syntax is
201-
related to that of :ref:`formatted string literals <f-strings>`, but it is
202-
less sophisticated and, in particular, does not support arbitrary expressions.
201+
related to that of :ref:`formatted string literals <f-strings>` and
202+
:ref:`template string literals <t-strings>`, but it is less sophisticated
203+
and, in particular, does not support arbitrary expressions.
203204

204205
.. index::
205206
single: {} (curly brackets); in string formatting
@@ -264,6 +265,8 @@ Some simple format string examples::
264265
"Weight in tons {0.weight}" # 'weight' attribute of first positional arg
265266
"Units destroyed: {players[0]}" # First element of keyword argument 'players'.
266267

268+
.. _formatstrings-conversion:
269+
267270
The *conversion* field causes a type coercion before formatting. Normally, the
268271
job of formatting a value is done by the :meth:`~object.__format__` method of the value
269272
itself. However, in some cases it is desirable to force a type to be formatted
@@ -306,7 +309,7 @@ Format Specification Mini-Language
306309

307310
"Format specifications" are used within replacement fields contained within a
308311
format string to define how individual values are presented (see
309-
:ref:`formatstrings` and :ref:`f-strings`).
312+
:ref:`formatstrings`, :ref:`f-strings`, and :ref:`t-strings`).
310313
They can also be passed directly to the built-in
311314
:func:`format` function. Each formattable type may define how the format
312315
specification is to be interpreted.
@@ -789,10 +792,20 @@ Nesting arguments and more complex examples::
789792

790793

791794

792-
.. _template-strings:
795+
.. _template-strings-pep292:
793796

794-
Template strings
795-
----------------
797+
Template strings ($-strings)
798+
----------------------------
799+
800+
.. note::
801+
802+
The feature described here was introduced in Python 2.4. It is unrelated
803+
to, and should not be confused with, the newer
804+
:ref:`template strings <template-strings>` and
805+
:ref:`t-string literal syntax <t-strings>` introduced in Python 3.14.
806+
T-string literals evaluate to instances of a different
807+
:class:`~string.templatelib.Template` class, found in the
808+
:mod:`string.templatelib` module.
796809

797810
Template strings provide simpler string substitutions as described in
798811
:pep:`292`. A primary use case for template strings is for

0 commit comments

Comments
 (0)