Source code:
———
Template strings
Added in version 3.14.
Template strings are a mechanism for custom string processing. They have the full flexibility of Python’s
, but return a
instance that gives access to the static and interpolated (in curly brackets) parts of a string before they are combined.
To write a t-string, use a 't' prefix instead of an 'f', like so:
>>> 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
classstring.templatelib.Template
The Template class describes the contents of a template string. It is immutable, meaning that attributes of a template cannot be reassigned.
The most common way to create a Template instance is to use the
template string literal syntax
. This syntax is identical to that of
, except that it uses a t prefix in place of an f:
>>> cheese='Red Leicester'>>> template=t"We're fresh out of {cheese}, sir.">>> type(template)<class 'string.templatelib.Template'>Templates are stored as sequences of literal
and dynamic
. A
attribute holds the values of the interpolations:
>>> cheese='Camembert'>>> template=t'Ah! We do have {cheese}.'>>> template.strings('Ah! We do have ', '.')>>> template.interpolations(Interpolation('Camembert', ...),)>>> template.values('Camembert',)The strings tuple has one more element than interpolations and values; the interpolations “belong” between the strings. This may be easier to understand when tuples are aligned
template.strings:('Ah! We do have ','.')template.values:('Camembert',)Attributes
strings:
[
,...]
A
of the static strings in the template.
>>> cheese='Camembert'>>> template=t'Ah! We do have {cheese}.'>>> template.strings('Ah! We do have ', '.')Empty strings are included in the tuple:
>>> response='We do have '>>> cheese='Camembert'>>> template=t'Ah! {response}{cheese}.'>>> template.strings('Ah! ', '', '.')The strings tuple is never empty, and always contains one more string than the interpolations and values tuples:
>>> t''.strings('',)>>> t''.values()>>> t'{'cheese'}'.strings('', '')>>> t'{'cheese'}'.values('cheese',)interpolations:
[
,...]
A
of the interpolations in the template.
>>> cheese='Camembert'>>> template=t'Ah! We do have {cheese}.'>>> template.interpolations(Interpolation('Camembert', 'cheese', None, ''),)The interpolations tuple may be empty and always contains one fewer values than the strings tuple:
>>> t'Red Leicester'.interpolations()values:
[
,...]
A tuple of all interpolated values in the template.
>>> cheese='Camembert'>>> template=t'Ah! We do have {cheese}.'>>> template.values('Camembert',)The values tuple always has the same length as the interpolations tuple. It is always equivalent to tuple(i.valueforiintemplate.interpolations).
Methods
__new__(*args:
|
)
While literal syntax is the most common way to create a Template, it is also possible to create them directly using the constructor:
>>> fromstring.templatelibimportInterpolation,Template>>> cheese='Camembert'>>> template=Template(... 'Ah! We do have ',Interpolation(cheese,'cheese'),'.'... )>>> list(template)['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']If multiple strings are passed consecutively, they will be concatenated into a single value in the
attribute. For example, the following code creates a Template with a single final string:
>>> fromstring.templatelibimportTemplate>>> template=Template('Ah! We do have ','Camembert','.')>>> template.strings('Ah! We do have Camembert.',)If multiple interpolations are passed consecutively, they will be treated as separate interpolations and an empty string will be inserted between them. For example, the following code creates a template with empty placeholders in the
attribute:
>>> fromstring.templatelibimportInterpolation,Template>>> template=Template(... Interpolation('Camembert','cheese'),... Interpolation('.','punctuation'),... )>>> template.strings('', '', '')iter(template)Iterate over the template, yielding each non-empty string and
in the correct order:
>>> cheese='Camembert'>>> list(t'Ah! We do have {cheese}.')['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']Caution
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+othertemplate+=otherConcatenate this template with another, returning a new Template instance:
>>> 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):
>>> fromstring.templatelibimportInterpolation,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, '')]classstring.templatelib.Interpolation
The Interpolation type represents an expression inside a template string. It is immutable, meaning that attributes of an interpolation cannot be reassigned.
Interpolations support pattern matching, allowing you to match against their attributes with the
:
>>> fromstring.templatelibimportInterpolation>>> interpolation=t'{1.+2.:.2f}'.interpolations[0]>>> interpolationInterpolation(3.0, '1. + 2.', None, '.2f')>>> matchinterpolation:... caseInterpolation(value,expression,conversion,format_spec):... print(value,expression,conversion,format_spec,sep=' | ')...3.0 | 1. + 2. | None | .2fInterpolations are
over the types of their values.
Attributes
value:
The evaluated value of the interpolation.
>>> t'{1+2}'.interpolations[0].value3expression:
For interpolations created by t-string literals, expression is the expression text found inside the curly brackets ({ & }), including any whitespace, excluding the curly brackets themselves, and ending before the first !, :, or = if any is present. For manually created interpolations, expression is the arbitrary string provided when constructing the interpolation instance.
We recommend using valid Python expressions or the empty string for the expression field of manually created Interpolation instances, although this is not enforced at runtime.
>>> t'{1+2}'.interpolations[0].expression'1 + 2'conversion:
['a','r','s']|
The conversion to apply to the value, or None.
The conversion is the optional conversion to apply to the value:
>>> t'{1+2!a}'.interpolations[0].conversion'a'Note
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
function can be used to mimic f-string conversion semantics.
format_spec:
The format specification to apply to the value.
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'Note
Unlike f-strings, where format specifications are applied automatically via the
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.
Methods
__new__(value:
, expression:
, conversion:
['a','r','s']|
=None, format_spec:
='')
Create a new Interpolation object from component parts.
Parameters:value – The evaluated, in-scope result of the interpolation.
expression – The text of a valid Python expression, or an empty string.
conversion – The
to be used, one of None, 'a', 'r', or 's'.
format_spec – An optional, arbitrary string used as the
to present the value.
Helper functions
string.templatelib.convert(obj, /, conversion)
Applies formatted string literal
semantics to the given object obj. This is frequently useful for custom template string processing logic.
Three conversion flags are currently supported:
's' which calls
on the value (like !s),
'r' which calls
(like !r), and
'a' which calls
(like !a).
If the conversion flag is None, obj is returned unchanged.