# `string.templatelib` — Suporte para literais de string template

Código-fonte: Lib/string/templatelib.py

Ver também

- Strings de formatação

- Sintaxe de literal de string template (t-string)

- PEP 750

## Strings template

Adicionado na versão 3.14.

Strings template são um mecanismo para processamento personalizado de strings. Elas têm toda a flexibilidade das Literais de strings formatadas do Python, mas retornam uma instância `Template` que dá acesso às partes estáticas e interpoladas (entre chaves) de uma string antes de serem combinadas.

Para escrever uma t-string, use um prefixo `'t'` em vez de `'f'`, assim:

    >>> pi = 3.14
    >>> t't-strings são novas no Python {pi!s}!'
    Template(
       strings=('t-strings são novas no Python ', '!'),
       interpolations=(Interpolation(3.14, 'pi', 's', ''),)
    )

## Tipos

class string.templatelib.Template

  A classe `Template` descreve o conteúdo de uma string template. Ela é imutável, o que significa que os atributos de um template não podem ser reatribuídos.

  A maneira mais comum de criar uma instância de `Template` é usar a sintaxe de literal de string template. Essa sintaxe é idêntica à de f-strings, exceto pelo fato de usar um prefixo `t` no lugar de um `f`:

      >>> cheese = 'Red Leicester'
      >>> template = t"We're fresh out of {cheese}, sir."
      >>> type(template)
      <class 'string.templatelib.Template'>

  Os templates são armazenados como sequências de literais `strings` e dinâmicos `interpolations`. Um atributo `values` contém os valores das interpolações:

      >>> cheese = 'Camembert'
      >>> template = t'Ah! We do have {cheese}.'
      >>> template.strings
      ('Ah! We do have ', '.')
      >>> template.interpolations
      (Interpolation('Camembert', ...),)
      >>> template.values
      ('Camembert',)

  A tupla `strings` tem um elemento a mais que `interpolations` e `values`; as interpolações “pertencem” às strings. Isso pode ser mais fácil de entender quando as tuplas estão alinhadas

      template.strings:  ('Ah! We do have ',              '.')
      template.values:   (                   'Camembert',    )

  Atributos

  strings: tuple [ str , ...]

    Uma `tuple` das strings estáticas no template.

        >>> cheese = 'Camembert'
        >>> template = t'Ah! We do have {cheese}.'
        >>> template.strings
        ('Ah! We do have ', '.')

    Strings vazias estão incluídas na tupla:

        >>> response = 'We do have '
        >>> cheese = 'Camembert'
        >>> template = t'Ah! {response}{cheese}.'
        >>> template.strings
        ('Ah! ', '', '.')

    A tupla `strings` nunca está vazia e sempre contém uma string a mais que as tuplas `interpolations` e `values`:

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

  interpolations: tuple [ Interpolation , ...]

    Uma `tuple` das interpolações no template.

        >>> cheese = 'Camembert'
        >>> template = t'Ah! We do have {cheese}.'
        >>> template.interpolations
        (Interpolation('Camembert', 'cheese', None, ''),)

    A tupla `interpolações` pode estar vazia e sempre contém um valor a menos que a tupla `strings`:

        >>> t'Red Leicester'.interpolations
        ()

  values: tuple [ object , ...]

    Uma tupla de todos os valores interpolados no template.

        >>> cheese = 'Camembert'
        >>> template = t'Ah! We do have {cheese}.'
        >>> template.values
        ('Camembert',)

    A tupla `values` sempre tem o mesmo comprimento que a tupla `interpolations`. Isso sempre equivale a `tuple(i.value for i in template.interpolations)`.

  Métodos

  __new__(*args: str | Interpolation )

    Embora a sintaxe de literal seja a maneira mais comum de criar um `Template`, também é possível criá-las diretamente usando o construtor:

        >>> from string.templatelib import Interpolation, Template
        >>> cheese = 'Camembert'
        >>> template = Template(
        ...     'Ah! We do have ', Interpolation(cheese, 'cheese'), '.'
        ... )
        >>> list(template)
        ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']

    Se várias strings forem passadas consecutivamente, elas serão concatenadas em um único valor no atributo `strings`. Por exemplo, o código a seguir cria uma `Template` com uma única string final:

        >>> from string.templatelib import Template
        >>> template = Template('Ah! We do have ', 'Camembert', '.')
        >>> template.strings
        ('Ah! We do have Camembert.',)

    Se várias interpolações forem passadas consecutivamente, elas serão tratadas como interpolações separadas e uma string vazia será inserida entre elas. Por exemplo, o código a seguir cria um modelo com espaços reservados vazios no atributo `strings`:

        >>> from string.templatelib import Interpolation, Template
        >>> template = Template(
        ...     Interpolation('Camembert', 'cheese'),
        ...     Interpolation('.', 'punctuation'),
        ... )
        >>> template.strings
        ('', '', '')

  iter(template)

    Itera sobre o template, produzindo cada string não-vazia e `Interpolation` em ordem correta.

        >>> cheese = 'Camembert'
        >>> list(t'Ah! We do have {cheese}.')
        ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']

    Cuidado

    Empty strings are not included in the iteration:

        >>> response = 'We do have '
        >>> cheese = 'Camembert'
        >>> list(t'Ah! {response}{cheese}.')
        ['Ah! ',
         Interpolation('We do have ', 'response', None, ''),
         Interpolation('Camembert', 'cheese', None, ''),
         '.']

  template + other
  template += other

    Concatena este template com outro, retornando uma nova instância `Template`:

        >>> cheese = 'Camembert'
        >>> list(t'Ah! ' + t'We do have {cheese}.')
        ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']

    Concatenating a `Template` and a `str` is not supported. This is because it is unclear 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 Interpolation, Template
        >>> template = t'Ah! '
        >>> # Treat 'We do have ' as a static string
        >>> template += Template('We do have ')
        >>> # Treat cheese as an interpolation
        >>> cheese = 'Camembert'
        >>> template += Template(Interpolation(cheese, 'cheese'))
        >>> list(template)
        ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '')]

class string.templatelib.Interpolation

  The `Interpolation` type represents an expression inside a template string. It is immutable, meaning that attributes of an interpolation cannot be reassigned.

  As interpolações oferecem suporte à correspondência de padrões, permitindo que você compare seus atributos com a instrução match:

      >>> from string.templatelib import Interpolation
      >>> interpolation = t'{1. + 2.:.2f}'.interpolations[0]
      >>> interpolation
      Interpolation(3.0, '1. + 2.', None, '.2f')
      >>> match interpolation:
      ...     case Interpolation(value, expression, conversion, format_spec):
      ...         print(value, expression, conversion, format_spec, sep=' | ')
      ...
      3.0 | 1. + 2. | None | .2f

  Atributos

  value: object

    O valor avaliado da interpolação.

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

  expression: str

    O texto de uma expressão Python válida ou uma string vazia.

    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: Literal ['a', 'r', 's'] | None

    A conversão a ser aplicada ao valor, ou `None`.

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

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

    Nota

    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 `conversion`. For convenience, the `convert()` function can be used to mimic f-string conversion semantics.

  format_spec: str

    A especificação de formato a ser aplicada ao valor.

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

    Nota

    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 interpolation will decide how to interpret and whether to apply the format specification. As a result, `format_spec` values in interpolations can be arbitrary strings, including those that do not conform to the `format()` protocol.

  Métodos

  __new__(value: object, expression: str, conversion: Literal ['a', 'r', 's'] | None = None, format_spec: str = '')

    Create a new `Interpolation` object from component parts.

    Parâmetros:

      - value – O resultado avaliado e dentro do escopo da interpolação.

      - expression – O texto de uma expressão Python válida ou uma string vazia.

      - conversion – The conversion to be used, one of `None`, `'a'`, `'r'`, or `'s'`.

      - format_spec – Uma string arbitrária opcional usada como especificação de formato para apresentar o valor.

## Funções auxiliares

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

  Aplica a semântica de conversão de literal de string formatada ao objeto obj fornecido. Isso é frequentemente útil para lógica de processamento de string template personalizada.

  Atualmente, há três sinalizadores de conversão suportados:

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

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

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

  Se o sinalizador de conversão é `None`, obj é retornado sem alterações.