string.templatelib.md

1> **Источник:** https://python-all.ru/3.16/library/string.templatelib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `string.templatelib` – Поддержка шаблонных строковых литералов89**Исходный код:** [Lib/string/templatelib.py](https://python-all.ru/src/main/Lib/string/templatelib.py)1011---1213> **См. также**14>15> - [Форматные строки](https://python-all.ru/3.16/reference/lexical_analysis.html#f-strings)16> - [Синтаксис шаблонного строкового литерала (t-строки)](https://python-all.ru/3.16/reference/lexical_analysis.html#t-strings)17> - [**PEP 750**](https://python-all.ru/3.16/library/string.templatelib.html)1819## Шаблонные строки2021Добавлено в версии 3.14.2223Шаблонные строки – это механизм для настраиваемой обработки строк. Они обладают всей гибкостью [f-строк](https://python-all.ru/3.16/reference/lexical_analysis.html#f-strings) Python, но возвращают экземпляр [`Template`](https://python-all.ru/3.16/library/string.templatelib.html#string.templatelib.Template), который предоставляет доступ к статическим и интерполированным (в фигурных скобках) частям строки *до* их объединения.2425Чтобы написать t-строку, используйте префикс `'t'` вместо `'f'`, например:2627```pycon28>>> pi = 3.1429>>> t't-strings are new in Python {pi!s}!'30Template(31   strings=('t-strings are new in Python ', '!'),32   interpolations=(Interpolation(3.14, 'pi', 's', ''),)33)34```3536## Типы3738#### `class string.templatelib.Template`3940Класс `Template` описывает содержимое шаблонной строки. Он неизменяем, то есть атрибуты шаблона нельзя переназначить.4142Самый распространённый способ создать экземпляр `Template` – использовать [синтаксис шаблонного строкового литерала](https://python-all.ru/3.16/reference/lexical_analysis.html#t-strings). Этот синтаксис идентичен синтаксису [f-строк](https://python-all.ru/3.16/reference/lexical_analysis.html#f-strings), за исключением того, что используется префикс `t` вместо `f`:4344```python45>>> cheese = 'Red Leicester'46>>> template = t"We're fresh out of {cheese}, sir."47>>> type(template)48<class 'string.templatelib.Template'>49```5051Шаблоны хранятся как последовательности литеральных [`strings`](https://python-all.ru/3.16/library/string.templatelib.html#string.templatelib.Template.strings) и динамических [`interpolations`](https://python-all.ru/3.16/library/string.templatelib.html#string.templatelib.Template.interpolations). Атрибут [`values`](https://python-all.ru/3.16/library/string.templatelib.html#string.templatelib.Template.values) содержит значения интерполяций:5253```python54>>> cheese = 'Camembert'55>>> template = t'Ah! We do have {cheese}.'56>>> template.strings57('Ah! We do have ', '.')58>>> template.interpolations59(Interpolation('Camembert', ...),)60>>> template.values61('Camembert',)62```6364Кортеж `strings` содержит на один элемент больше, чем `interpolations` и `values`; интерполяции «находятся» между строками. Это может быть легче понять, если выровнять кортежи6566```python67template.strings:  ('Ah! We do have ',              '.')68template.values:   (                   'Camembert',    )69```7071Атрибуты7273#### `strings: tuple[str, ...]`7475Кортеж [`tuple`](https://python-all.ru/3.16/library/stdtypes.html#tuple) статических строк шаблона.7677```python78>>> cheese = 'Camembert'79>>> template = t'Ah! We do have {cheese}.'80>>> template.strings81('Ah! We do have ', '.')82```8384Пустые строки *включаются* в кортеж:8586```python87>>> response = 'We do have '88>>> cheese = 'Camembert'89>>> template = t'Ah! {response}{cheese}.'90>>> template.strings91('Ah! ', '', '.')92```9394Кортеж `strings` никогда не бывает пустым и всегда содержит на одну строку больше, чем кортежи `interpolations` и `values`:9596```python97>>> t''.strings98('',)99>>> t''.values100()101>>> t'{'cheese'}'.strings102('', '')103>>> t'{'cheese'}'.values104('cheese',)105```106107#### `interpolations: tuple[Interpolation, ...]`108109Кортеж [`tuple`](https://python-all.ru/3.16/library/stdtypes.html#tuple) интерполяций шаблона.110111```python112>>> cheese = 'Camembert'113>>> template = t'Ah! We do have {cheese}.'114>>> template.interpolations115(Interpolation('Camembert', 'cheese', None, ''),)116```117118Кортеж `interpolations` может быть пустым и всегда содержит на одно значение меньше, чем кортеж `strings`:119120```python121>>> t'Red Leicester'.interpolations122()123```124125#### `values: tuple[object, ...]`126127Кортеж всех интерполированных значений шаблона.128129```python130>>> cheese = 'Camembert'131>>> template = t'Ah! We do have {cheese}.'132>>> template.values133('Camembert',)134```135136Кортеж `values` всегда имеет ту же длину, что и кортеж `interpolations`. Он всегда эквивалентен `tuple(i.value for i in template.interpolations)`.137138Методы139140#### `__new__(*args: str | Interpolation)`141142Хотя литеральный синтаксис – самый распространённый способ создать `Template`, также можно создать их напрямую с помощью конструктора:143144```python145>>> from string.templatelib import Interpolation, Template146>>> cheese = 'Camembert'147>>> template = Template(148...     'Ah! We do have ', Interpolation(cheese, 'cheese'), '.'149... )150>>> list(template)151['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']152```153154Если несколько строк передаются последовательно, они будут объединены в одно значение в атрибуте [`strings`](https://python-all.ru/3.16/library/string.templatelib.html#string.templatelib.Template.strings). Например, следующий код создаёт `Template` с единственной конечной строкой:155156```python157>>> from string.templatelib import Template158>>> template = Template('Ah! We do have ', 'Camembert', '.')159>>> template.strings160('Ah! We do have Camembert.',)161```162163Если несколько интерполяций передаются последовательно, они будут обрабатываться как отдельные интерполяции, и между ними будет вставлена пустая строка. Например, следующий код создаёт шаблон с пустыми заполнителями в атрибуте [`strings`](https://python-all.ru/3.16/library/string.templatelib.html#string.templatelib.Template.strings):164165```python166>>> from string.templatelib import Interpolation, Template167>>> template = Template(168...     Interpolation('Camembert', 'cheese'),169...     Interpolation('.', 'punctuation'),170... )171>>> template.strings172('', '', '')173```174175#### `iter(template)`176177Обходит шаблон, возвращая каждую непустую строку и [`Interpolation`](https://python-all.ru/3.16/library/string.templatelib.html#string.templatelib.Interpolation) в правильном порядке:178179```python180>>> cheese = 'Camembert'181>>> list(t'Ah! We do have {cheese}.')182['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']183```184185> **Внимание**186>187> Пустые строки **не** включаются в итерацию:188>189> ```python190> >>> response = 'We do have '191> >>> cheese = 'Camembert'192> >>> list(t'Ah! {response}{cheese}.')193> ['Ah! ',194>  Interpolation('We do have ', 'response', None, ''),195>  Interpolation('Camembert', 'cheese', None, ''),196>  '.']197> ```198199#### `template + other`200201#### `template += other`202203Объединяет этот шаблон с другим, возвращая новый экземпляр `Template`:204205```python206>>> cheese = 'Camembert'207>>> list(t'Ah! ' + t'We do have {cheese}.')208['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']209```210211Объединение `Template` и `str` **не** поддерживается. Это связано с тем, что неясно, следует ли трактовать строку как статическую строку или интерполяцию. Если требуется объединить `Template` со строкой, следует либо обернуть строку непосредственно в `Template` (чтобы трактовать её как статическую строку), либо использовать `Interpolation` (для обработки как динамической):212213```python214>>> from string.templatelib import Interpolation, Template215>>> template = t'Ah! '216>>> # Считаем 'We do have ' статической строкой217>>> template += Template('We do have ')218>>> # Считаем cheese интерполяцией219>>> cheese = 'Camembert'220>>> template += Template(Interpolation(cheese, 'cheese'))221>>> list(template)222['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '')]223```224225#### `class string.templatelib.Interpolation`226227Тип `Interpolation` представляет выражение внутри строки-шаблона. Он неизменяем, то есть атрибутам интерполяции нельзя присвоить новые значения.228229Интерполяции поддерживают сопоставление с образцом, что позволяет сопоставлять их атрибуты с помощью [инструкции match](https://python-all.ru/3.16/reference/compound_stmts.html#match):230231```python232>>> from string.templatelib import Interpolation233>>> interpolation = t'{1. + 2.:.2f}'.interpolations[0]234>>> interpolation235Interpolation(3.0, '1. + 2.', None, '.2f')236>>> match interpolation:237...     case Interpolation(value, expression, conversion, format_spec):238...         print(value, expression, conversion, format_spec, sep=' | ')239...2403.0 | 1. + 2. | None | .2f241```242243Интерполяции являются [обобщёнными](https://python-all.ru/3.16/library/typing.html#generics) по типам своих значений.244245Атрибуты246247#### `value: object`248249Вычисленное значение интерполяции.250251```python252>>> t'{1 + 2}'.interpolations[0].value2533254```255256#### `expression: str`257258Для интерполяций, созданных литералами t-строк, `expression` – это текст выражения, находящийся внутри фигурных скобок (`{` и `}`), включая любые пробельные символы, исключая сами фигурные скобки, и заканчивающийся перед первой `!`, `:` или `=`, если таковые присутствуют. Для интерполяций, созданных вручную, `expression` – это произвольная строка, указанная при создании экземпляра интерполяции.259260Рекомендуется использовать корректные выражения Python или пустую строку для поля `expression` вручную созданных экземпляров `Interpolation`, хотя это не проверяется во время выполнения.261262```python263>>> t'{1 + 2}'.interpolations[0].expression264'1 + 2'265```266267#### `conversion: Literal['a', 'r', 's'] | None`268269Преобразование, применяемое к значению, или `None`.270271`conversion` – это необязательное преобразование, применяемое к значению:272273```python274>>> t'{1 + 2!a}'.interpolations[0].conversion275'a'276```277278> **Примечание**279>280> В отличие от f-строк, где преобразования применяются автоматически, ожидаемое поведение для t-строк заключается в том, что код, *обрабатывающий* `Template`, сам решает, как интерпретировать и применять ли `conversion`. Для удобства можно использовать функцию [`convert()`](https://python-all.ru/3.16/library/string.templatelib.html#string.templatelib.convert), чтобы имитировать семантику преобразований f-строк.281282#### `format_spec: str`283284Спецификация формата, применяемая к значению.285286`format_spec` – это необязательная произвольная строка, используемая как спецификация формата для представления значения:287288```python289>>> t'{1 + 2:.2f}'.interpolations[0].format_spec290'.2f'291```292293> **Примечание**294>295> В отличие от f-строк, где спецификации формата применяются автоматически через протокол [`format()`](https://python-all.ru/3.16/library/functions.html#format), ожидаемое поведение для t-строк заключается в том, что код, *обрабатывающий* интерполяцию, сам решает, как интерпретировать и применять ли спецификацию формата. В результате значения `format_spec` в интерполяциях могут быть произвольными строками, включая те, которые не соответствуют протоколу `format()`.296297Методы298299#### `__new__(value: object, expression: str, conversion: Literal['a', 'r', 's'] | None = None, format_spec: str = '')`300301Создаёт новый объект `Interpolation` из составных частей.302303**Параметры:**304305- **value** – вычисленный результат интерполяции, находящийся в области видимости.306- **expression** – текст корректного выражения Python или пустая строка.307- **conversion** – [преобразование](https://python-all.ru/3.16/library/string.html#formatstrings), которое нужно использовать: `None`, `'a'`, `'r'` или `'s'`.308- **format\_spec** – необязательная произвольная строка, используемая как [спецификация формата](https://python-all.ru/3.16/library/string.html#formatspec) для представления значения.309310## Вспомогательные функции311312#### `string.templatelib.convert(obj, /, conversion)`313314Применяет семантику [преобразования](https://python-all.ru/3.16/library/string.html#formatstrings-conversion) форматированной строки к указанному объекту *obj*. Это часто полезно для логики обработки пользовательских строк-шаблонов.315316В настоящее время поддерживаются три флага преобразования:317318- `'s'`, который вызывает [`str()`](https://python-all.ru/3.16/library/stdtypes.html#str) для значения (как `!s`),319- `'r'`, который вызывает [`repr()`](https://python-all.ru/3.16/library/functions.html#repr) (как `!r`), и320- `'a'`, который вызывает [`ascii()`](https://python-all.ru/3.16/library/functions.html#ascii) (как `!a`).321322Если флаг преобразования равен `None`, *obj* возвращается без изменений.323