string.templatelib – Поддержка шаблонных строковых литералов¶string.templatelib – Support for template string literals

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

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

Чтобы написать t-строку, используйте префикс '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', ''),)
)

Типы¶Types

class string.templatelib.Template¶

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

Самый распространённый способ создать экземпляр Template – использовать синтаксис шаблонного строкового литерала. Этот синтаксис идентичен синтаксису f-строк, за исключением того, что используется префикс t вместо f:

>>> 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! '
>>> # Считаем '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:

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

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

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

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

format_spec: str¶

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

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

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

Примечание

В отличие от f-строк, где спецификации формата применяются автоматически через протокол 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 – преобразование, которое нужно использовать: None, 'a', 'r' или 's'.

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

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

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

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

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

• 's', который вызывает str() для значения (как !s),

• 'r', который вызывает repr() (как !r), и

• 'a', который вызывает ascii() (как !a).

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