string.templatelib --- Hỗ trợ cho chuỗi ký tự mẫu

Source code: Lib/string/templatelib.py

Xem thêm

Chuỗi mẫu

Added in version 3.14.

Chuỗi mẫu là một cơ chế để xử lý chuỗi tùy chỉnh. Chúng có toàn bộ tính linh hoạt của dây f của Python, nhưng trả về một phiên bản Template cho phép truy cập vào các phần tĩnh và nội suy (trong dấu ngoặc nhọn) của chuỗi before mà chúng được kết hợp.

Để viết chuỗi chữ T, hãy sử dụng tiền tố 't' thay vì 'f', như sau:

>>> pi = 3,14
>>> chuỗi t là tính năng mới trong Python {pi!s}!'
Mẫu(
   strings=('t-strings là mới trong Python ', '!'),
   interpolations=(Nội suy(3.14, 'pi', 's', ''),)
)

Các loại

class string.templatelib.Template

Lớp Template mô tả nội dung của chuỗi mẫu. Nó là bất biến, có nghĩa là các thuộc tính của mẫu không thể được gán lại.

Cách phổ biến nhất để tạo phiên bản Template là sử dụng template string literal syntax. Cú pháp này giống hệt với cú pháp của f-strings, ngoại trừ việc nó sử dụng tiền tố t thay cho f:

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

Các mẫu được lưu trữ dưới dạng chuỗi strings theo nghĩa đen và interpolations động. Thuộc tính values chứa các giá trị của các phép nội suy:

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

Bộ strings có nhiều phần tử hơn interpolations và values; các phép nội suy “thuộc về” giữa các chuỗi. Điều này có thể dễ hiểu hơn khi các bộ dữ liệu được căn chỉnh

template.strings: ('À! Chúng tôi có ', '.')
template.values: ( 'Camembert', )

Thuộc tính

strings: tuple[str, ...]

Một tuple của các chuỗi tĩnh trong mẫu.

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

Các chuỗi trống are có trong bộ dữ liệu:

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

Bộ strings không bao giờ trống và luôn chứa nhiều hơn một chuỗi so với bộ interpolations và values:

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

Một tuple các phép nội suy trong mẫu.

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

Bộ dữ liệu interpolations có thể trống và luôn chứa ít hơn một giá trị so với bộ dữ liệu strings:

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

Một bộ gồm tất cả các giá trị được nội suy trong mẫu.

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

Bộ dữ liệu values luôn có cùng độ dài với bộ dữ liệu interpolations. Nó luôn tương đương với tuple(i.value for i in template.interpolations).

phương pháp

__new__(*args: str | Interpolation)

Mặc dù cú pháp bằng chữ là cách phổ biến nhất để tạo Template, nhưng bạn cũng có thể tạo chúng trực tiếp bằng cách sử dụng hàm tạo:

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

Nếu nhiều chuỗi được truyền liên tiếp, chúng sẽ được nối thành một giá trị duy nhất trong thuộc tính strings. Ví dụ: đoạn mã sau tạo Template với một chuỗi cuối cùng:

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

Nếu nhiều phép nội suy được truyền liên tiếp, chúng sẽ được coi là các phép nội suy riêng biệt và một chuỗi trống sẽ được chèn vào giữa chúng. Ví dụ: đoạn mã sau tạo một mẫu có phần giữ chỗ trống trong thuộc tính strings:

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

Lặp lại mẫu, thu được từng chuỗi không trống và Interpolation theo đúng thứ tự:

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

Cảnh báo

Các chuỗi trống được not bao gồm trong lần lặp:

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

Ghép nối mẫu này với mẫu khác, trả về một phiên bản Template mới:

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

Việc ghép nối Template và str được hỗ trợ not. Điều này là do không rõ chuỗi này nên được coi là chuỗi tĩnh hay chuỗi nội suy. Nếu bạn muốn nối Template với một chuỗi, bạn nên bọc chuỗi đó trực tiếp trong Template (để coi nó là một chuỗi tĩnh) hoặc sử dụng Interpolation (để coi nó là động):

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

Loại Interpolation đại diện cho một biểu thức bên trong chuỗi mẫu. Nó là bất biến, có nghĩa là các thuộc tính của phép nội suy không thể được gán lại.

Nội suy hỗ trợ khớp mẫu, cho phép bạn so khớp với các thuộc tính của chúng bằng 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

Thuộc tính

value: object

Giá trị được đánh giá của phép nội suy.

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

Đối với các phép nội suy được tạo bởi các chuỗi ký tự chữ t, expression là văn bản biểu thức được tìm thấy bên trong dấu ngoặc nhọn ({ & }), bao gồm mọi khoảng trắng, ngoại trừ chính dấu ngoặc nhọn và kết thúc trước !, : hoặc = đầu tiên nếu có. Đối với các phép nội suy được tạo thủ công, expression là chuỗi tùy ý được cung cấp khi xây dựng phiên bản nội suy.

Chúng tôi khuyên bạn nên sử dụng các biểu thức Python hợp lệ hoặc chuỗi trống cho trường expression của các phiên bản Interpolation được tạo thủ công, mặc dù điều này không được thực thi trong thời gian chạy.

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

Việc chuyển đổi để áp dụng cho giá trị hoặc None.

conversion là chuyển đổi tùy chọn để áp dụng cho giá trị:

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

Ghi chú

Không giống như chuỗi f, nơi các chuyển đổi được áp dụng tự động, hành vi dự kiến với chuỗi t là mã mà processes, Template sẽ quyết định cách diễn giải và có áp dụng conversion hay không. Để thuận tiện, hàm convert() có thể được sử dụng để bắt chước ngữ nghĩa chuyển đổi chuỗi f.

format_spec: str

Đặc tả định dạng để áp dụng cho giá trị.

Zz000zz là một chuỗi tùy ý, tùy chọn được sử dụng làm đặc tả định dạng để trình bày giá trị:

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

Ghi chú

Không giống như chuỗi f, trong đó thông số định dạng được áp dụng tự động thông qua giao thức format(), hoạt động dự kiến với chuỗi t là mã mà phép nội suy processes sẽ quyết định cách diễn giải và có áp dụng thông số định dạng hay không. Do đó, các giá trị format_spec trong phép nội suy có thể là các chuỗi tùy ý, bao gồm cả những chuỗi không tuân thủ giao thức format().

phương pháp

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

Tạo một đối tượng Interpolation mới từ các bộ phận thành phần.

Tham số:

  • value -- Kết quả được đánh giá trong phạm vi của phép nội suy.

  • expression -- Văn bản của biểu thức Python hợp lệ hoặc một chuỗi trống.

  • conversion -- Zz000zz sẽ được sử dụng, một trong các None, 'a', 'r' hoặc 's'.

  • format_spec -- Một chuỗi tùy ý, tùy ý được sử dụng làm format specification để trình bày giá trị.

Chức năng trợ giúp

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

Áp dụng ngữ nghĩa conversion theo chuỗi được định dạng cho đối tượng obj đã cho. Điều này thường hữu ích cho logic xử lý chuỗi mẫu tùy chỉnh.

Ba cờ chuyển đổi hiện được hỗ trợ:

  • 's' gọi str() theo giá trị (như !s),

  • 'r' gọi repr() (như !r) và

  • 'a' gọi ascii() (như !a).

Nếu cờ chuyển đổi là None, obj được trả về không thay đổi.