string.templatelib — 對模板字串字面量的支援

原始碼: Lib/string/templatelib.py

參見

模板字串

在 3.14 版本加入。

模板字串是一種自定義字串處理機制。它們具有 Python f-strings 的全部靈活性，但在它們組合**之前**返回一個 Template 例項，該例項允許訪問字串的靜態部分和內插（在花括號中）部分。

要編寫 t-string，請使用 '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-strings 的語法相同，只是它使用 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! '
>>> # 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

對於由 t-string 字面量建立的內插，expression 是花括號（{ 和 }）內的表示式文字，包括任何空白，但不包括花括號本身，並且在第一個 !、: 或 = 之前結束（如果存在）。對於手動建立的內插，expression 是在構造內插例項時提供的任意字串。

我們建議為手動建立的 Interpolation 例項的 expression 欄位使用有效的 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-strings 不同，f-strings 會自動應用轉換，t-strings 的預期行為是**處理** Template 的程式碼將決定如何解釋和是否應用 conversion。為了方便起見，convert() 函式可用於模仿 f-string 轉換語義。

format_spec: str

要應用於值的格式規範。

format_spec 是一個可選的任意字串，用作呈現值的格式規範。

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

備註

與 f-strings 不同，f-strings 會透過 format() 協議自動應用格式規範，t-strings 的預期行為是**處理**內插的程式碼將決定如何解釋和是否應用格式規範。因此，內插中的 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* 未更改。