Jun 6, 2025 · Jun 8, 2025 · Jun 8, 2025 · Jun 8, 2025 · Jun 8, 2025 · Jun 8, 2025
diff --git a/Doc/glossary.rst b/Doc/glossary.rst

      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>`.  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
                            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
   .. 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
 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

 "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.
   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
diff --git a/Doc/library/string.templatelib.rst b/Doc/library/string.templatelib.rst
 :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, ...]

       A :ref:`tuple <tut-tuples>` 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, ...]

       A tuple of the interpolations in the template.

       >>> name = "World"
       >>> print(t"Hello {name}!".interpolations)
       (Interpolation('World', 'name', None, ''),)


   .. attribute:: values
       :type: tuple[Any, ...]

       A tuple of all interpolated values 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.
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst

 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` arenot supported.

 The forms ``signed_number '+' NUMBER`` and ``signed_number '-' NUMBER`` are
 for expressing :ref:`complex numbers <imaginary>`; they require a real number
diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst
 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
  :mod:`string.templatelib` module.

 - 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,
  prior to being passed to the :class:`~string.templatelib.Interpolation` object.

 - When the equal 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

 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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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)
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand DownExpand Up		@@ -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.
Expand DownExpand Up		@@ -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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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` arenot supported.

		The forms ``signed_number '+' NUMBER`` and ``signed_number '-' NUMBER`` are
		for expressing :ref:`complex numbers <imaginary>`; they require a real number
Expand Down