string.templatelib — Support for template string literals

Source code: Lib/string/templatelib.py

See also

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.