gh-132661: Document t-strings and templatelib

Doc/glossary.rst

@@ -462,7 +462,7 @@ Glossary
  core and with user code.
 
  f-string
- String literals prefixed with ``'f'`` or ``'F'`` are commonly called
+ String literals prefixed with ``f`` or ``F`` are commonly called
  "f-strings" which is short for
  :ref:`formatted string literals <f-strings>`. See also :pep:`498`.
 
@@ -1322,6 +1322,11 @@ Glossary
 
  See also :term:`borrowed reference`.
 
+ t-string
+ String literals prefixed with ``t`` or ``T`` are commonly called
+ "t-strings" which is short for
+ :ref:`template string literals <t-strings>`.
+
  text encoding
  A string in Python is a sequence of Unicode code points (in range
  ``U+0000``--``U+10FFFF``). To store or transfer a string, it needs to be

Doc/library/ast.rst

@@ -289,9 +289,9 @@ Literals
  * ``conversion`` is an integer:
 
  * -1: no formatting
- * 115: ``!s`` string formatting
- * 114: ``!r`` repr formatting
- * 97: ``!a`` ascii formatting
+ * 115 (``ord('s')``): ``!s`` string formatting
+ * 114 (``ord('r')``): ``!r`` repr formatting
+ * 97 (``ord('a')``): ``!a`` ASCII formatting
 
  * ``format_spec`` is a :class:`JoinedStr` node representing the formatting
  of the value, or ``None`` if no format was specified. Both
@@ -325,6 +325,54 @@ Literals
  Constant(value='.3')]))]))
 
 
+.. class:: TemplateStr(values)
+
+ A t-string, comprising a series of :class:`Interpolation` and :class:`Constant`
+ nodes.
+
+ .. doctest::
+
+ >>> print(ast.dump(ast.parse('t"{name} finished{place:ordinal}"', mode='eval'), indent=4))
+ Expression(
+ body=TemplateStr(
+ values=[
+ Interpolation(
+ value=Name(id='name'),
+ str='name',
+ conversion=-1),
+ Constant(value=' finished '),
+ Interpolation(
+ value=Name(id='place'),
+ str='place',
+ conversion=-1,
+ format_spec=JoinedStr(
+ values=[
+ Constant(value='ordinal')]))]))
+
+ .. versionadded:: 3.14
+
+
+.. class:: Interpolation(value, str, conversion, format_spec)
+
+ Node representing a single interpolation field in a t-string.
+
+ * ``value`` is any expression node (such as a literal, a variable, or a
+ function call).
+ * ``str`` is a constant containing the text of the interpolation expression.
+ * ``conversion`` is an integer:
+
+ * -1: no conversion
+ * 115: ``!s`` string conversion
+ * 114: ``!r`` repr conversion
+ * 97: ``!a`` ascii conversion
+
+ * ``format_spec`` is a :class:`JoinedStr` node representing the formatting
+ of the value, or ``None`` if no format was specified. Both
+ ``conversion`` and ``format_spec`` can be set at the same time.
+
+ .. versionadded:: 3.14
+
+
 .. class:: List(elts, ctx)
  Tuple(elts, ctx)
 

Doc/library/dis.rst

@@ -1120,6 +1120,48 @@ iterations of the loop.
  .. versionadded:: 3.12
 
 
+.. opcode:: BUILD_TEMPLATE
+
+ Constructs a new :class:`~string.templatelib.Template` from a tuple
+ of strings and a tuple of interpolations and pushes the resulting instance
+ onto the stack::
+
+ interpolations = STACK.pop()
+ strings = STACK.pop()
+ STACK.append(_build_template(strings, interpolations))
+
+ .. versionadded:: 3.14
+
+
+.. opcode:: BUILD_INTERPOLATION (format)
+
+ Constructs a new :class:`~string.templatelib.Interpolation` from a
+ value and its source expression and pushes the resulting instance onto the
+ stack.
+
+ If no conversion or format specification is present, ``format`` is set to
+ ``2``.
+
+ If the low bit of ``format`` is set, it indicates that the interpolation
+ contains a format specification.
+
+ If ``format >> 2`` is non-zero, it indicates that the interpolation
+ contains a conversion. The value of ``format >> 2`` is the conversion type
+ (``0`` for no conversion, ``1`` for ``!s``, ``2`` for ``!r``, and
+ ``3`` for ``!a``)::
+
+ conversion = format >> 2
+ if format & 1:
+ format_spec = STACK.pop()
+ else:
+ format_spec = None
+ expression = STACK.pop()
+ value = STACK.pop()
+ STACK.append(_build_interpolation(value, expression, conversion, format_spec))
+
+ .. versionadded:: 3.14
+
+
 .. opcode:: BUILD_TUPLE (count)
 
  Creates a tuple consuming *count* items from the stack, and pushes the

Doc/library/stdtypes.rst

@@ -2675,9 +2675,9 @@ For example:
  lead to a number of common errors (such as failing to display tuples and
  dictionaries correctly). Using the newer :ref:`formatted string literals
  <f-strings>`, the :meth:`str.format` interface, or :ref:`template strings
- <template-strings>` may help avoid these errors. Each of these
- alternatives provides their own trade-offs and benefits of simplicity,
- flexibility, and/or extensibility.
+($-strings) <template-strings-pep292>` may help avoid these errors.
+Each of these alternatives provides their own trade-offs and benefits of
+simplicity, flexibility, and/or extensibility.
 
 String objects have one unique built-in operation: the ``%`` operator (modulo).
 This is also known as the string *formatting* or *interpolation* operator.

Doc/library/string.rst

@@ -198,8 +198,9 @@ Format String Syntax
 The :meth:`str.format` method and the :class:`Formatter` class share the same
 syntax for format strings (although in the case of :class:`Formatter`,
 subclasses can define their own format string syntax). The syntax is
-related to that of :ref:`formatted string literals <f-strings>`, but it is
-less sophisticated and, in particular, does not support arbitrary expressions.
+related to that of :ref:`formatted string literals <f-strings>` and
+:ref:`template string literals <t-strings>`, but it is less sophisticated
+and, in particular, does not support arbitrary expressions.
 
 .. index::
  single:{} (curly brackets); in string formatting
@@ -264,6 +265,8 @@ Some simple format string examples::
  "Weight in tons{0.weight}" # 'weight' attribute of first positional arg
  "Units destroyed:{players[0]}" # First element of keyword argument 'players'.
 
+.. _formatstrings-conversion:
+
 The *conversion* field causes a type coercion before formatting. Normally, the
 job of formatting a value is done by the :meth:`~object.__format__` method of the value
 itself. However, in some cases it is desirable to force a type to be formatted
@@ -306,7 +309,7 @@ Format Specification Mini-Language
 
 "Format specifications" are used within replacement fields contained within a
 format string to define how individual values are presented (see
-:ref:`formatstrings`and :ref:`f-strings`).
+:ref:`formatstrings`, :ref:`f-strings`, and :ref:`t-strings`).
 They can also be passed directly to the built-in
 :func:`format` function. Each formattable type may define how the format
 specification is to be interpreted.
@@ -789,10 +792,20 @@ Nesting arguments and more complex examples::
 
 
 
-.. _template-strings:
+.. _template-strings-pep292:
 
-Template strings
-----------------
+Template strings ($-strings)
+----------------------------
+
+.. note::
+
+ The feature described here was introduced in Python 2.4. It is unrelated
+ to, and should not be confused with, the newer
+ :ref:`template strings <template-strings>` and
+ :ref:`t-string literal syntax <t-strings>` introduced in Python 3.14.
+ T-string literals evaluate to instances of a different
+ :class:`~string.templatelib.Template` class, found in the
+ :mod:`string.templatelib` module.
 
 Template strings provide simpler string substitutions as described in
 :pep:`292`. A primary use case for template strings is for