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