string.templatelib — Stöd för mallsträngslitteraler

Källkod: Lib/string/templatelib.py

Se även

Mall för strängar

Tillagd i version 3.14.

Template strings är en mekanism för anpassad strängbehandling. De har samma flexibilitet som Pythons f-strängar, men returnerar en Template-instans som ger tillgång till de statiska och interpolerade (inom hakparenteser) delarna av en sträng innan de kombineras.

För att skriva en t-sträng använder du ett 't'-prefix istället för ett 'f', så här:

>>> 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', ''),)
)

Typer

class string.templatelib.Template

Klassen Template beskriver innehållet i en mallsträng. Den är oföränderlig, vilket innebär att attribut i en mall inte kan tilldelas på nytt.

Det vanligaste sättet att skapa en Template-instans är att använda template string literal syntax. Denna syntax är identisk med den för f-strings, förutom att den använder ett t-prefix i stället för ett f:

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

Mallar lagras som sekvenser av bokstavliga strings och dynamiska interpolations. Ett attribut values innehåller värdena för interpoleringen:

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

Tupeln strings har ett element mer än interpolations och values; interpolationerna ”hör hemma” mellan strängarna. Detta kan vara lättare att förstå när tuplerna är inriktade

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

Attribut

strings: tuple[str, ...]

En tupel av de statiska strängarna i mallen.

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

Tomma strängar inkluderas i tupeln:

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

Tupeln strings är aldrig tom och innehåller alltid en sträng mer än tuplarna interpolations och values:

>>> t''.strings
('',)
>>> t''.values
()
>>> t'{'cheese'}'.strings
('', '')
>>> t'{'cheese'}'.values
('cheese',)
interpolations: tuple[Interpolation, ...]

En tupel av interpoleringarna i mallen.

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

Tupeln interpolations kan vara tom och innehåller alltid ett värde mindre än tupeln strings:

>>> t'Red Leicester'.interpolations
()
values: tuple[object, ...]

En tupel av alla interpolerade värden i mallen.

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

Tupeln values har alltid samma längd som tupeln interpolations. Den är alltid ekvivalent med tuple(i.value for i in template.interpolations).

Metoder

__new__(*args: str | Interpolation)

Även om litteral syntax är det vanligaste sättet att skapa en Template, är det också möjligt att skapa dem direkt med hjälp av konstruktören:

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

Om flera strängar skickas i följd kommer de att sammanfogas till ett enda värde i attributet strings. Följande kod skapar t.ex. en Template med en enda slutsträng:

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

Om flera interpoleringar skickas i följd kommer de att behandlas som separata interpoleringar och en tom sträng kommer att infogas mellan dem. Följande kod skapar t.ex. en mall med tomma platshållare i attributet strings:

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

Iterera över mallen, vilket ger varje icke-tom sträng och Interpolation i rätt ordning:

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

Försiktighet

Tomma strängar ingår inte i iterationen:

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

Sammanfoga denna mall med en annan och returnera en ny Template-instans:

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

Att sammanfoga en Template och en str stöds inte. Detta beror på att det är oklart om strängen ska behandlas som en statisk sträng eller en interpolation. Om du vill konkatenera en Template med en sträng, bör du antingen linda in strängen direkt i en Template (för att behandla den som en statisk sträng) eller använda en Interpolation (för att behandla den som dynamisk):

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

Typen Interpolation representerar ett uttryck inuti en mallsträng. Den är oföränderlig, vilket innebär att attribut för en interpolation inte kan tilldelas på nytt.

Interpolationer stöder mönstermatchning, vilket gör att du kan matcha mot deras attribut med match statement:

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

Attribut

value: object

Det utvärderade värdet för interpoleringen.

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

Texten i ett giltigt Python-uttryck, eller en tom sträng.

expression är originaltexten för interpolerings Python-uttryck, om interpoleringen skapades från en t-string-litteral. Utvecklare som skapar interpoleringen manuellt bör antingen sätta detta till en tom sträng eller välja ett lämpligt giltigt Python-uttryck.

>>> t'{1 + 2}'.interpolations[0].expression
'1 + 2'
conversion: Literal['a', 'r', 's'] | None

Den konvertering som ska tillämpas på värdet, eller None.

conversion är den valfria konvertering som ska tillämpas på värdet:

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

Anteckning

Till skillnad från f-strängar, där konverteringar tillämpas automatiskt, är det förväntade beteendet med t-strängar att kod som behandlar Template bestämmer hur den ska tolka och om den ska tillämpa conversion. För enkelhetens skull kan funktionen convert() användas för att efterlikna semantiken för konvertering av f-strängar.

format_spec: str

Den formatspecifikation som ska tillämpas på värdet.

format_spec är en valfri, godtycklig sträng som används som formatspecifikation för att presentera värdet:

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

Anteckning

Till skillnad från f-strängar, där formatspecifikationer tillämpas automatiskt via protokollet format(), är det förväntade beteendet med t-strängar att koden som bearbetar interpoleringen bestämmer hur formatspecifikationen ska tolkas och om den ska tillämpas. Som ett resultat kan format_spec-värden i interpoleringar vara godtyckliga strängar, inklusive de som inte överensstämmer med format()-protokollet.

Metoder

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

Skapa ett nytt Interpolation-objekt av olika komponenter.

Parametrar:

  • value – Det utvärderade resultatet av interpoleringen, inom räckvidden.

  • expression – Texten i ett giltigt Python-uttryck, eller en tom sträng.

  • conversion – Den konvertering som ska användas, en av None, 'a', 'r' eller 's'.

  • format_spec – En valfri, godtycklig sträng som används som formatspecifikation för att presentera värdet.

Hjälpfunktioner

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

Tillämpar formaterad strängbokstäver konvertering semantik på det givna objektet obj. Detta är ofta användbart för anpassad logik för bearbetning av mallsträngar.

Tre konverteringsflaggor stöds för närvarande:

  • 's' som anropar str() på värdet (som !s),

  • 'r' som anropar repr() (som !r), och

  • 'a' som anropar ascii() (som !a).

Om konverteringsflaggan är None returneras obj oförändrad.