string.templatelib — поддержка литералов шаблонных строк

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

Шаблонные строки — это механизм для пользовательской обработки строк. Они обладают всей гибкостью f-строк Python, но возвращают экземпляр Template, который предоставляет доступ к статическим и интерполированным (в фигурных скобках) частям строки до их объединения.

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

>>> 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 создаётся с помощью синтаксиса литералов шаблонных строк. Этот синтаксис идентичен синтаксису f-строк, за исключением того, что вместо префикса f используется префикс t:

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

Шаблоны хранятся как последовательности литеральных строк strings и динамических interpolations. Атрибут values содержит значения интерполяций:

>>> 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; интерполяции «располагаются» между строками. Это проще понять, если выровнять кортежи:

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

Атрибуты

strings: tuple[str, ...]

tuple статических строк в шаблоне.

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

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

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

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

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

interpolations: tuple[Interpolation, ...]

tuple интерполяций в шаблоне.

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

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

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

values: tuple[object, ...]

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

>>> 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, его также можно создать напрямую с помощью конструктора:

>>> 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. Например, следующий код создаёт Template с одной последней строкой:

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

Если несколько интерполяций переданы подряд, они будут обработаны как отдельные интерполяции, а между ними будет вставлена пустая строка. Например, следующий код создаёт шаблон с пустыми заполнителями в атрибуте strings:

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

iter(template)

Перебирает шаблон, возвращая каждую непустую строку и Interpolation в правильном порядке:

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

Внимание

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

>>> 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:

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

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

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

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

Интерполяции поддерживают сопоставление с образцом, позволяя сопоставлять их атрибуты с помощью оператора 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

Интерполяции являются обобщёнными относительно типов своих значений.

Атрибуты

value: object

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

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

expression: str

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

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

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

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

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

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

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

Примечание

В отличие от f-строк, где преобразования применяются автоматически, при использовании т-строк предполагается, что код, обрабатывающий Template, сам решит, как интерпретировать и применять ли conversion. Для удобства можно использовать функцию convert(), чтобы имитировать семантику преобразования f-строк.

format_spec: str

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

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

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

Примечание

В отличие от f-строк, где спецификации формата применяются автоматически с помощью протокола format(), при использовании т-строк предполагается, что код, обрабатывающий интерполяцию, сам решит, как интерпретировать и применять ли спецификацию формата. Поэтому значения format_spec в интерполяциях могут быть произвольными строками, в том числе не соответствующими протоколу format().

Методы

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

Создаёт новый объект Interpolation из отдельных компонентов.

Параметры:

• value – Вычисленный результат интерполяции в текущей области видимости.
• expression – Текст допустимого выражения Python или пустая строка.
• conversion – Используемое преобразование: одно из None, 'a', 'r' или 's'.
• format_spec – Необязательная произвольная строка, используемая как спецификация формата для представления значения.

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

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

Применяет к заданному объекту obj семантику преобразования литерала форматируемой строки. Это часто полезно для пользовательской логики обработки шаблонных строк.

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

• 's', вызывающий str() для значения (как !s),
• 'r', вызывающий repr() (как !r), и
• 'a', вызывающий ascii() (как !a).

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