# `string.templatelib` — Support for template string literals

Source code: Lib/string/templatelib.py

See also

- Format strings

- T-string literal syntax

## Template strings

Added in version 3.14.

Template strings are a formatting mechanism that allows for deep control over how strings are processed. You can create templates using t-string literal syntax, which is identical to f-string syntax but uses a `t` instead of an `f`. While f-strings evaluate to `str`, t-strings create a `Template` instance that gives you access to the static and interpolated (in curly braces) parts of a string before they are combined.

## Template

The `Template` class describes the contents of a template string.

`Template` instances are immutable: their attributes cannot be reassigned.

class string.templatelib.Template(*args)

  Create a new `Template` object.

  Parameters:

    args (str | Interpolation) – A mix of strings and `Interpolation` instances in any order.

  The most common way to create a `Template` instance is to use the t-string literal syntax. This syntax is identical to that of f-strings except that it uses a `t` instead of an `f`:

      >>> name = "World"
      >>> template = t"Hello {name}!"
      >>> type(template)
      <class 'string.templatelib.Template'>

  Templates ars stored as sequences of literal `strings` and dynamic `interpolations`. A `values` attribute holds the interpolation values:

      >>> template.strings
      ('Hello ', '!')
      >>> template.interpolations
      (Interpolation('World', ...),)
      >>> template.values
      ('World',)

  The `strings` tuple has one more element than `interpolations` and `values`; the interpolations “belong” between the strings. This may be easier to understand when tuples are aligned:

      template.strings:  ('Hello ',          '!')
      template.values:   (          'World',    )

  While literal syntax is the most common way to create `Template` instances, it is also possible to create them directly using the constructor:

      >>> from string.templatelib import Interpolation, Template
      >>> name = "World"
      >>> template = Template("Hello, ", Interpolation(name, "name"), "!")
      >>> list(template)
      ['Hello, ', Interpolation('World', 'name', None, ''), '!']

  If two or more consecutive strings are passed, they will be concatenated into a single value in the `strings` attribute. For example, the following code creates a `Template` with a single final string:

      >>> from string.templatelib import Template
      >>> template = Template("Hello ", "World", "!")
      >>> template.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 empty placeholders in the `strings` attribute:

      >>> from string.templatelib import Interpolation, Template
      >>> template = Template(Interpolation("World", "name"), Interpolation("!", "punctuation"))
      >>> template.strings
      ('', '', '')

  strings: tuple[str, ...]

    A tuple of the static strings in the template.

        >>> name = "World"
        >>> t"Hello {name}!".strings
        ('Hello ', '!')

    Empty strings are included in the tuple:

        >>> name = "World"
        >>> t"Hello {name}{name}!".strings
        ('Hello ', '', '!')

    The `strings` tuple is never empty, and always contains one more string than the `interpolations` and `values` tuples:

        >>> t"".strings
        ('',)
        >>> t"".values
        ()
        >>> t"{'cheese'}".strings
        ('', '')
        >>> t"{'cheese'}".values
        ('cheese',)

  interpolations: tuple[Interpolation, ...]

    A tuple of the interpolations in the template.

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

    The `interpolations` tuple may be empty and always contains one fewer values than the `strings` tuple:

        >>> t"Hello!".interpolations
        ()

  values: tuple[Any, ...]

    A tuple of all interpolated values in the template.

        >>> name = "World"
        >>> t"Hello {name}!".values
        ('World',)

    The `values` tuple always has the same length as the `interpolations` tuple. It is equivalent to `tuple(i.value for i in template.interpolations)`.

  iter(template)

    Iterate over the template, yielding each string and `Interpolation` in order.

        >>> name = "World"
        >>> list(t"Hello {name}!")
        ['Hello ', Interpolation('World', 'name', None, ''), '!']

    Empty strings are not included in the iteration:

        >>> name = "World"
        >>> list(t"Hello {name}{name}")
        ['Hello ', Interpolation('World', 'name', None, ''), Interpolation('World', 'name', None, '')]

  template + other
  template += other

    Concatenate this template with another, returning a new `Template` instance:

        >>> name = "World"
        >>> list(t"Hello " + t"there {name}!")
        ['Hello there ', Interpolation('World', 'name', None, ''), '!']

    Concatenation between a `Template` and a `str` is not supported. This is because it is ambiguous whether the string should be treated as a static string or an interpolation. If you want to concatenate a `Template` with a string, you should either wrap the string directly in a `Template` (to treat it as a static string) or use an `Interpolation` (to treat it as dynamic):

        >>> from string.templatelib import Template, Interpolation
        >>> template = t"Hello "
        >>> # Treat "there " as a static string
        >>> template += Template("there ")
        >>> # Treat name as an interpolation
        >>> name = "World"
        >>> template += Template(Interpolation(name, "name"))
        >>> list(template)
        ['Hello there ', Interpolation('World', 'name', None, '')]

class string.templatelib.Interpolation(value, expression='', conversion=None, format_spec='')

  Create a new `Interpolation` object.

  Parameters:

    - value (object) – The evaluated, in-scope result of the interpolation.

    - expression (str) – The text of a valid Python expression, or an empty string.

    - conversion (`Literal["a", "r", "s"] | None`) – The optional conversion to be used, one of r, s, and a.

    - format_spec (str) – An optional, arbitrary string used as the format specification to present the value.

  The `Interpolation` type represents an expression inside a template string.

  `Interpolation` instances are immutable: their attributes cannot be reassigned.

  value
    Returns:

      The evaluated value of the interpolation.

    Type:

      object

        >>> t"{1 + 2}".interpolations[0].value
        3

  expression
    Returns:

      The text of a valid Python expression, or an empty string.

    Type:

      str

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

        >>> t"{1 + 2}".interpolations[0].expression
        '1 + 2'

  conversion
    Returns:

      The conversion to apply to the value, or `None`.

    Type:

      `Literal["a", "r", "s"] | None`

    The `Interpolation.conversion` is the optional conversion to apply to the value:

        >>> t"{1 + 2!a}".interpolations[0].conversion
        'a'

    Note

    Unlike f-strings, where conversions are applied automatically, the expected behavior with t-strings is that code that processes the `Template` will decide how to interpret and whether to apply the `Interpolation.conversion`.

  format_spec
    Returns:

      The format specification to apply to the value.

    Type:

      str

    The `Interpolation.format_spec` is an optional, arbitrary string used as the format specification to present the value:

        >>> t"{1 + 2:.2f}".interpolations[0].format_spec
        '.2f'

    Note

    Unlike f-strings, where format specifications are applied automatically via the `format()` protocol, the expected behavior with t-strings is that code that processes the `Template` will decide how to interpret and whether to apply the format specification. As a result, `Interpolation.format_spec` values in `Template` instances can be arbitrary strings, even those that do not necessarily conform to the rules of Python’s `format()` protocol.

  Interpolations support pattern matching, allowing you to match against their attributes with the match statement:

      >>> from string.templatelib import Interpolation
      >>> interpolation = Interpolation(3.0, "1 + 2", None, ".2f")
      >>> match interpolation:
      ...     case Interpolation(value, expression, conversion, format_spec):
      ...         print(value, expression, conversion, format_spec)
      ...
      3.0 1 + 2 None .2f

## Helper functions

string.templatelib.convert(obj, /, conversion)

  Applies formatted string literal conversion semantics to the given object obj. This is frequently useful for custom template string processing logic.

  Three conversion flags are currently supported:

  - `'s'` which calls `str()` on the value,

  - `'r'` which calls `repr()`, and

  - `'a'` which calls `ascii()`.

  If the conversion flag is `None`, obj is returned unchanged.