> **Источник:** https://python-all.ru/3.15/library/string.templatelib.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# `string.templatelib` – Поддержка шаблонных строковых литералов

**Исходный код:** [Lib/string/templatelib.py](https://python-all.ru/src/3.15/Lib/string/templatelib.py)

---

> **См. также**
>
> - [Форматные строки](https://python-all.ru/3.15/reference/lexical_analysis.html#f-strings)
> - [Синтаксис шаблонного строкового литерала (t-строки)](https://python-all.ru/3.15/reference/lexical_analysis.html#t-strings)
> - [**PEP 750**](https://python-all.ru/3.15/library/string.templatelib.html)

## Шаблонные строки

Добавлено в версии 3.14.

Шаблонные строки – это механизм для настраиваемой обработки строк. Они обладают всей гибкостью [f-строк](https://python-all.ru/3.15/reference/lexical_analysis.html#f-strings) Python, но возвращают экземпляр [`Template`](https://python-all.ru/3.15/library/string.templatelib.html#string.templatelib.Template), который предоставляет доступ к статическим и интерполированным (в фигурных скобках) частям строки *до* их объединения.

Чтобы написать t-строку, используйте префикс `'t'` вместо `'f'`, например:

```pycon
>>> pi = 3.14
>>> t't-strings are new in Python {pi!s}!'
Template(
   strings=('t-strings are new in Python ', '!'),
   interpolations=(Interpolation(3.14, 'pi', 's', ''),)
)
```

## Типы

#### `class string.templatelib.Template`

Класс `Template` описывает содержимое шаблонной строки. Он неизменяем, то есть атрибуты шаблона нельзя переназначить.

Самый распространённый способ создать экземпляр `Template` – использовать [синтаксис шаблонного строкового литерала](https://python-all.ru/3.15/reference/lexical_analysis.html#t-strings). Этот синтаксис идентичен синтаксису [f-строк](https://python-all.ru/3.15/reference/lexical_analysis.html#f-strings), за исключением того, что используется префикс `t` вместо `f`:

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

Шаблоны хранятся как последовательности литеральных [`strings`](https://python-all.ru/3.15/library/string.templatelib.html#string.templatelib.Template.strings) и динамических [`interpolations`](https://python-all.ru/3.15/library/string.templatelib.html#string.templatelib.Template.interpolations). Атрибут [`values`](https://python-all.ru/3.15/library/string.templatelib.html#string.templatelib.Template.values) содержит значения интерполяций:

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

Кортеж `strings` содержит на один элемент больше, чем `interpolations` и `values`; интерполяции «находятся» между строками. Это может быть легче понять, если выровнять кортежи

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

Атрибуты

#### `strings: tuple[str, ...]`

Кортеж [`tuple`](https://python-all.ru/3.15/library/stdtypes.html#tuple) статических строк шаблона.

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

Пустые строки *включаются* в кортеж:

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

Кортеж `strings` никогда не бывает пустым и всегда содержит на одну строку больше, чем кортежи `interpolations` и `values`:

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

#### `interpolations: tuple[Interpolation, ...]`

Кортеж [`tuple`](https://python-all.ru/3.15/library/stdtypes.html#tuple) интерполяций шаблона.

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

Кортеж `interpolations` может быть пустым и всегда содержит на одно значение меньше, чем кортеж `strings`:

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

#### `values: tuple[object, ...]`

Кортеж всех интерполированных значений шаблона.

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

Кортеж `values` всегда имеет ту же длину, что и кортеж `interpolations`. Он всегда эквивалентен `tuple(i.value for i in template.interpolations)`.

Методы

#### `__new__(*args: str | Interpolation)`

Хотя литеральный синтаксис – самый распространённый способ создать `Template`, также можно создать их напрямую с помощью конструктора:

```python
>>> 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, ''), '.']
```

Если несколько строк передаются последовательно, они будут объединены в одно значение в атрибуте [`strings`](https://python-all.ru/3.15/library/string.templatelib.html#string.templatelib.Template.strings). Например, следующий код создаёт `Template` с единственной конечной строкой:

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

Если несколько интерполяций передаются последовательно, они будут обрабатываться как отдельные интерполяции, и между ними будет вставлена пустая строка. Например, следующий код создаёт шаблон с пустыми заполнителями в атрибуте [`strings`](https://python-all.ru/3.15/library/string.templatelib.html#string.templatelib.Template.strings):

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

#### `iter(template)`

Обходит шаблон, возвращая каждую непустую строку и [`Interpolation`](https://python-all.ru/3.15/library/string.templatelib.html#string.templatelib.Interpolation) в правильном порядке:

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

> **Внимание**
>
> Пустые строки **не** включаются в итерацию:
>
> ```python
> >>> 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`

Объединяет этот шаблон с другим, возвращая новый экземпляр `Template`:

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

Объединение `Template` и `str` **не** поддерживается. Это связано с тем, что неясно, следует ли трактовать строку как статическую строку или интерполяцию. Если требуется объединить `Template` со строкой, следует либо обернуть строку непосредственно в `Template` (чтобы трактовать её как статическую строку), либо использовать `Interpolation` (для обработки как динамической):

```python
>>> from string.templatelib import Interpolation, Template
>>> template = t'Ah! '
>>> # Считаем 'We do have ' статической строкой
>>> template += Template('We do have ')
>>> # Считаем cheese интерполяцией
>>> cheese = 'Camembert'
>>> template += Template(Interpolation(cheese, 'cheese'))
>>> list(template)
['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '')]
```

#### `class string.templatelib.Interpolation`

Тип `Interpolation` представляет выражение внутри строки-шаблона. Он неизменяем, то есть атрибутам интерполяции нельзя присвоить новые значения.

Интерполяции поддерживают сопоставление с образцом, что позволяет сопоставлять их атрибуты с помощью [инструкции match](https://python-all.ru/3.15/reference/compound_stmts.html#match):

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

Интерполяции являются [обобщёнными](https://python-all.ru/3.15/library/typing.html#generics) по типам своих значений.

Атрибуты

#### `value: object`

Вычисленное значение интерполяции.

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

#### `expression: str`

Для интерполяций, созданных литералами t-строк, `expression` – это текст выражения, находящийся внутри фигурных скобок (`{` и `}`), включая любые пробельные символы, исключая сами фигурные скобки, и заканчивающийся перед первой `!`, `:` или `=`, если таковые присутствуют. Для интерполяций, созданных вручную, `expression` – это произвольная строка, указанная при создании экземпляра интерполяции.

Рекомендуется использовать корректные выражения Python или пустую строку для поля `expression` вручную созданных экземпляров `Interpolation`, хотя это не проверяется во время выполнения.

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

#### `conversion: Literal['a', 'r', 's'] | None`

Преобразование, применяемое к значению, или `None`.

`conversion` – это необязательное преобразование, применяемое к значению:

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

> **Примечание**
>
> В отличие от f-строк, где преобразования применяются автоматически, ожидаемое поведение для t-строк заключается в том, что код, *обрабатывающий* `Template`, сам решает, как интерпретировать и применять ли `conversion`. Для удобства можно использовать функцию [`convert()`](https://python-all.ru/3.15/library/string.templatelib.html#string.templatelib.convert), чтобы имитировать семантику преобразований f-строк.

#### `format_spec: str`

Спецификация формата, применяемая к значению.

`format_spec` – это необязательная произвольная строка, используемая как спецификация формата для представления значения:

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

> **Примечание**
>
> В отличие от f-строк, где спецификации формата применяются автоматически через протокол [`format()`](https://python-all.ru/3.15/library/functions.html#format), ожидаемое поведение для t-строк заключается в том, что код, *обрабатывающий* интерполяцию, сам решает, как интерпретировать и применять ли спецификацию формата. В результате значения `format_spec` в интерполяциях могут быть произвольными строками, включая те, которые не соответствуют протоколу `format()`.

Методы

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

Создаёт новый объект `Interpolation` из составных частей.

**Параметры:**

- **value** – вычисленный результат интерполяции, находящийся в области видимости.
- **expression** – текст корректного выражения Python или пустая строка.
- **conversion** – [преобразование](https://python-all.ru/3.15/library/string.html#formatstrings), которое нужно использовать: `None`, `'a'`, `'r'` или `'s'`.
- **format\_spec** – необязательная произвольная строка, используемая как [спецификация формата](https://python-all.ru/3.15/library/string.html#formatspec) для представления значения.

## Вспомогательные функции

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

Применяет семантику [преобразования](https://python-all.ru/3.15/library/string.html#formatstrings-conversion) форматированной строки к указанному объекту *obj*. Это часто полезно для логики обработки пользовательских строк-шаблонов.

В настоящее время поддерживаются три флага преобразования:

- `'s'`, который вызывает [`str()`](https://python-all.ru/3.15/library/stdtypes.html#str) для значения (как `!s`),
- `'r'`, который вызывает [`repr()`](https://python-all.ru/3.15/library/functions.html#repr) (как `!r`), и
- `'a'`, который вызывает [`ascii()`](https://python-all.ru/3.15/library/functions.html#ascii) (как `!a`).

Если флаг преобразования равен `None`, *obj* возвращается без изменений.