python · hugovk · Jul 22, 2025 · Jun 6, 2025 · Jun 8, 2025 · Jun 8, 2025
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
@@ -1304,6 +1304,11 @@ Glossary
 
       See also :term:`borrowed reference`.
 
+   t-string
-   t-string
+   t-string
+   t-strings
-   t-string
+   t-string
+   t-strings
+      String literals prefixed with ``'t'`` or ``'T'`` are commonly called
+      "t-strings" which is short for
+      :ref:`template string literals <t-strings>`.  See also :pep:`750`.
+
    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

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
@@ -324,6 +324,49 @@ Literals
                             values=[
                                 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')]))]))
+
+
+.. class:: Interpolation(value, str, int, 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.
+
 
 .. class:: List(elts, ctx)
            Tuple(elts, ctx)

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
@@ -1120,6 +1120,45 @@ 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 an
+   expression and its source text and pushes the resulting instance onto the
+   stack.
+
+   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
+   (e.g. ``0`` for no conversion, ``1`` for ``!s``, ``2`` for ``!r``, and
+   ``3`` for ``!a``)::
+
+      if format & 1:
+          format_spec = STACK.pop()
+      else:
+          format_spec = None
+      conversion = format >> 2
+      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

diff --git a/Doc/library/string.rst b/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.
-and, in particular, does not support arbitrary expressions.
+and, in particular, does not support arbitrary expressions in interpolations.
-and, in particular, does not support arbitrary expressions.
+and, in particular, does not support arbitrary expressions in interpolations.
 
 .. index::
    single: {} (curly brackets); in string formatting
@@ -306,7 +307,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.
@@ -972,3 +973,9 @@ Helper functions
    or ``None``, runs of whitespace characters are replaced by a single space
    and leading and trailing whitespace are removed, otherwise *sep* is used to
    split and join the words.
+
+
+
+.. toctree::
+
+   string.templatelib.rst
@@ -0,0 +1,184 @@
+:mod:`!string.templatelib` --- Templates and Interpolations for t-strings
+=========================================================================
+
+.. module:: string.templatelib
+   :synopsis: Support for t-string literals.
+
+**Source code:** :source:`Lib/string/templatelib.py`
+
+--------------
+
+
+.. seealso::
+
+   :ref:`Format strings <f-strings>`
+
+
+.. _templatelib-template:
+
+Template
+--------
+
+The :class:`!Template` class describes the contents of a template string.
+
+The most common way to create a new :class:`!Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`Template` that can be used to format strings:
+
+   >>> name = "World"
+   >>> greeting = t"Hello {name}!"
+   >>> type(greeting)
+   <class 'string.templatelib.Template'>
+   >>> print(list(greeting))
+   ['Hello ', Interpolation('World', 'name', None, ''), '!']
+
+It is also possible to create a :class:`!Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances:
+
+   >>> from string.templatelib import Interpolation, Template
+   >>> name = "World"
+   >>> greeting = Template("Hello, ", Interpolation(name, "name"), "!")
+   >>> print(list(greeting))
+   ['Hello, ', Interpolation('World', 'name', None, ''), '!']
+
+.. class:: Template(*args)
+
+   Create a new :class:`!Template` object.
+
+   :param args: A mix of strings and :class:`Interpolation` instances in any order.
+   :type args: str | Interpolation
+
+   If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`Template` with a single final string:
+
+   >>> from string.templatelib import Template
+   >>> greeting = Template("Hello ", "World", "!")
+   >>> print(greeting.strings)
+   ('Hello World!',)
+
+   If two or more consecutive interpolations are passed, they will be treated as separate interpolations and an empty string will be inserted between them. For example, the following code creates a template with a single value in the :attr:`~Template.strings` attribute:
+
+   >>> from string.templatelib import Interpolation, Template
+   >>> greeting = Template(Interpolation("World", "name"), Interpolation("!", "punctuation"))
+   >>> print(greeting.strings)
+   ('', '', '')
+
+   .. attribute:: strings
+       :type: tuple[str, ...]
-   .. attribute:: strings
-       :type: tuple[str, ...]
+   .. attribute:: strings
+      :type: tuple[str, ...]
-   .. attribute:: strings
-       :type: tuple[str, ...]
+   .. attribute:: strings
+      :type: tuple[str, ...]
+
+       A :ref:`tuple <tut-tuples>` of the static strings in the template.
-       A :ref:`tuple <tut-tuples>` of the static strings in the template.
+       A :class:`tuple` of the static strings in the template.
-       A :ref:`tuple <tut-tuples>` of the static strings in the template.
+       A :class:`tuple` of the static strings in the template.
+
+       >>> name = "World"
+       >>> print(t"Hello {name}!".strings)
+       ('Hello ', '!')
+
+       Empty strings *are* included in the tuple:
+
+       >>> name = "World"
+       >>> print(t"Hello {name}{name}!".strings)
+       ('Hello ', '', '!')
+
+   .. attribute:: interpolations
+       :type: tuple[Interpolation, ...]
-   .. attribute:: interpolations
-       :type: tuple[Interpolation, ...]
+   .. attribute:: interpolations
+      :type: tuple[Interpolation, ...]
-   .. attribute:: interpolations
-       :type: tuple[Interpolation, ...]
+   .. attribute:: interpolations
+      :type: tuple[Interpolation, ...]
+
+       A tuple of the interpolations in the template.
+
+       >>> name = "World"
+       >>> print(t"Hello {name}!".interpolations)
+       (Interpolation('World', 'name', None, ''),)
+
+
+   .. attribute:: values
+       :type: tuple[Any, ...]
-   .. attribute:: values
-       :type: tuple[Any, ...]
+   .. attribute:: values
+      :type: tuple[Any, ...]
-   .. attribute:: values
-       :type: tuple[Any, ...]
+   .. attribute:: values
+      :type: tuple[Any, ...]
+
+       A tuple of all interpolated values in the template.
-       A tuple of all interpolated values in the template.
+       A tuple of the values of every interpolation in the template.
-       A tuple of all interpolated values in the template.
+       A tuple of the values of every interpolation in the template.
+
+       >>> name = "World"
+       >>> print(t"Hello {name}!".values)
+       ('World',)
+
+   .. method:: __iter__()
+
+       Iterate over the template, yielding each string and :class:`Interpolation` in order.
+
+       >>> name = "World"
+       >>> print(list(t"Hello {name}!"))
+       ['Hello ', Interpolation('World', 'name', None, ''), '!']
+
+       Empty strings are *not* included in the iteration:
+
+       >>> name = "World"
+       >>> print(list(t"Hello {name}{name}"))
+       ['Hello ', Interpolation('World', 'name', None, ''), Interpolation('World', 'name', None, '')]
+
+       :returns: An iterable of all the parts in the template.
+       :rtype: typing.Iterator[str | Interpolation]
+
+.. class:: Interpolation(*args)
+
+   Create a new :class:`!Interpolation` object.
+
+   :param value: The evaluated, in-scope result of the interpolation.
+   :type value: object
+
+   :param expression: The original *text* of the interpolation's Python :ref:`expressions <expressions>`.
+   :type expression: str
+
+   :param conversion: The optional :ref:`conversion <formatstrings>` to be used, one of r, s, and a,.
+   :type value: Literal["a", "r", "s"] | None
+
+   :param format_spec: An optional, arbitrary string used as the :ref:`format specification <formatspec>` to present the value.
+
+   The :class:`!Interpolation` type represents an expression inside a template string. It is shallow immutable -- its attributes cannot be reassigned.
+
+   >>> name = "World"
+   >>> template = t"Hello {name}"
+   >>> template.interpolations[0].value
+   'World'
+   >>> template.interpolations[0].value = "Galaxy"
+   Traceback (most recent call last):
+     File "<input>", line 1, in <module>
+   AttributeError: readonly attribute
+
+   While f-strings and t-strings are largely similar in syntax and expectations, the :attr:`~Interpolation.conversion` and :attr:`~Interpolation.format_spec` behave differently. With f-strings, these are applied to the resulting value automatically. For example, in this ``format_spec``:
+
+   >>> value = 42
+   >>> f"Value: {value:.2f}"
+   'Value: 42.00'
+
+   With a t-string :class:`!Interpolation`, the template function is expected to apply this to the value:
+
+   >>> value = 42
+   >>> template = t"Value: {value:.2f}"
+   >>> template.interpolations[0].value
+   42
+
+   .. property:: __match_args__
+
+       :returns: A tuple of the attributes to use for structural pattern matching.
+       :rtype: (Literal["value"], Literal["expression"], Literal["conversion"], Literal["format_spec"])
+
+
+   .. property:: value
+
+       :returns: The evaluated value of the interpolation.
+       :rtype: object
+
+   .. property:: expression
+
+       :returns: The original text of the interpolation's Python expression if the interpolation was created from a t-string literal
+       :rtype: str
+
+       The :attr:`~Interpolation.expression` is the original text of the interpolation's Python expression, if the interpolation was created from a t-string literal. Developers creating
+       interpolations manually should either set this to an empty
+       string or choose a suitable valid python expression.
+
+   .. property:: conversion
+
+      :returns: The conversion to apply to the value, one of "a", "r", or "s", or None.
+      :rtype: Literal["a", "r", "s"] | None
+
+      The :attr:`~Interpolation.conversion` is the optional conversion to apply to the value. This is one of "a", "r", or "s", or None if no conversion is specified.
+
+   .. property:: format_spec
+
+      :returns: The format specification to apply to the value.
+      :rtype: str
+
+      The :attr:`~Interpolation.format_spec` is an optional, arbitrary string used as the format specification to present the value. This is similar to the format specification used in :ref:`format strings <formatstrings>`, but it is not limited to a specific set of formats.
@@ -852,8 +852,8 @@ A literal pattern corresponds to most
 
 The rule ``strings`` and the token ``NUMBER`` are defined in the
 :doc:`standard Python grammar <./grammar>`.  Triple-quoted strings are
-supported.  Raw strings and byte strings are supported.  :ref:`f-strings` are
-not supported.
+supported.  Raw strings and byte strings are supported.  :ref:`f-strings`
+and :ref:`t-strings` are not supported.
 
 The forms ``signed_number '+' NUMBER`` and ``signed_number '-' NUMBER`` are
 for expressing :ref:`complex numbers <imaginary>`; they require a real number

@@ -913,6 +913,44 @@ See also :pep:`498` for the proposal that added formatted string literals,
 and :meth:`str.format`, which uses a related format string mechanism.
 
 
+.. _t-strings:
+.. _template-string-literals:
+
+t-strings
+---------
+
+.. versionadded:: 3.14
+
+A :dfn:`template string literal` or :dfn:`t-string` is a string literal
+that is prefixed with ``'t'`` or ``'T'``.  These strings follow the same
+syntax and evaluation rules as :ref:`formatted string literals <f-strings>`, with
+the following differences:
+
+- Rather than evaluating to a ``str`` object, t-strings evaluate to a
+  :class:`~string.templatelib.Template` object from the
- Rather than evaluating to a ``str`` object, t-strings evaluate to a
-  :class:`~string.templatelib.Template` object from the
+* Rather than evaluating to a ``str`` object, template string literals evaluate
+  to a :class:`~string.templatelib.Template` object from the
- Rather than evaluating to a ``str`` object, t-strings evaluate to a
-  :class:`~string.templatelib.Template` object from the
+* Rather than evaluating to a ``str`` object, template string literals evaluate
+  to a :class:`~string.templatelib.Template` object from the
+  :mod:`string.templatelib` module.
+
+- The :func:`format` protocol is not used. Instead, the format specifier and
- The :func:`format` protocol is not used. Instead, the format specifier and
+* The :func:`format` protocol is not used. Instead, the format specifier and
- The :func:`format` protocol is not used. Instead, the format specifier and
+* The :func:`format` protocol is not used. Instead, the format specifier and
+  conversions (if any) are passed to a new :class:`~string.templatelib.Interpolation`
+  object that is created for each evaluated expression. It is up to code that
+  processes the resulting :class:`~string.templatelib.Template` object to
+  decide how to handle format specifiers and conversions.
+
+- Format specifiers containing nested replacement fields are evaluated eagerly,
- Format specifiers containing nested replacement fields are evaluated eagerly,
+* Format specifiers containing nested replacement fields are evaluated eagerly,
- Format specifiers containing nested replacement fields are evaluated eagerly,
+* Format specifiers containing nested replacement fields are evaluated eagerly,
+  prior to being passed to the :class:`~string.templatelib.Interpolation` object.
+
+- When the equal sign ``'='`` is provided in an interpolation expression, the
- When the equal sign ``'='`` is provided in an interpolation expression, the
+* When the equals sign ``'='`` is provided in an interpolation expression, the
- When the equal sign ``'='`` is provided in an interpolation expression, the
+* When the equals sign ``'='`` is provided in an interpolation expression, the
+  resulting :class:`~string.templatelib.Template` object will have the expression
+  text along with a ``'='`` character placed in its
+  :attr:`~string.templatelib.Template.strings` attribute. The
+  :attr:`~string.templatelib.Template.interpolations` attribute will also
+  contain an ``Interpolation`` instance for the expression. By default, the
+  :attr:`~string.templatelib.Interpolation.conversion` attribute will be set to
+  ``'r'`` (i.e. :func:`repr`), unless there is a conversion explicitly specified
+  (in which case it overrides the default) or a format specifier is provided (in
+  which case, the ``conversion`` defaults to ``None``).
+
+
 .. _numbers:
 
 Numeric literals
@@ -1044,7 +1082,7 @@ readability::
 
 Either of these parts, but not both, can be empty. For example::
 
-   10.  # (equivalent to 10.0)
+   1.   # (equivalent to 10.0)
    .001  # (equivalent to 0.001)
 
 Optionally, the integer and fraction may be followed by an *exponent*:

diff --git a/Doc/sphinx-warnings.txt b/Doc/sphinx-warnings.txt