string — Common string operations

Вихідний код: Lib/string.py

---

Дивись також

Тип текстової послідовності — str

Рядкові методи

Рядкові константи

Константи, визначені в цьому модулі:

string.ascii_letters

Конкатенація констант ascii_lowercase і ascii_uppercase описана нижче. Це значення не залежить від локалі.

string.ascii_lowercase

Малі літери 'abcdefghijklmnopqrstuvwxyz''. Це значення не залежить від локалі та не зміниться.

string.ascii_uppercase

Великі літери 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Це значення не залежить від локалі та не зміниться.

string.digits

Рядок '0123456789''.

string.hexdigits

Рядок '0123456789abcdefABCDEF.

string.octdigits

Рядок '01234567.

string.punctuation

Рядок символів ASCII, які вважаються знаками пунктуації в локалі C:!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~.

string.printable

Рядок символів ASCII, які вважаються друкованими. Це комбінація digits, ascii_letters, punctuation і whitespace.

string.whitespace

Рядок, що містить усі символи ASCII, які вважаються пробілами. Це включає символи пробілу, табуляції, переходу рядка, повернення, переходу форми та вертикальної табуляції.

Спеціальне форматування рядків

Вбудований клас рядків надає можливість робити складні заміни змінних і форматувати значення за допомогою методу format(), описаного в PEP 3101. Клас Formatter в модулі string дозволяє вам створювати та налаштовувати власну поведінку форматування рядків, використовуючи ту саму реалізацію, що й вбудований метод format().

class string.Formatter

Клас Formatter має такі публічні методи:

format(format_string, /, *args, **kwargs)

Основний метод API. Він приймає рядок формату та довільний набір позиційних і ключових аргументів. Це просто оболонка, яка викликає vformat().

Змінено в версії 3.7: Аргумент формату рядка тепер позиційний лише.

vformat(format_string, args, kwargs)

Ця функція виконує фактичну роботу з форматування. Вона представлена як окрема функція для випадків, коли ви хочете передати попередньо визначений словник аргументів, а не розпаковувати та перепаковувати словник як окремі аргументи за допомогою синтаксису *args і **kwargs. vformat() розбиває рядок формату на символьні дані та поля заміни. Він викликає різні методи, описані нижче.

Крім того, Formatter визначає ряд методів, які мають бути замінені підкласами:

parse(format_string)

Перейдіть до format_string і поверніть ітерацію кортежів (literal_text, field_name, format_spec, conversion). Це використовується vformat(), щоб розбити рядок на буквальний текст або поля заміни.

Значення в кортежі концептуально представляють проміжок літерального тексту, за яким слідує одне поле заміни. Якщо буквального тексту немає (що може статися, якщо два поля заміни зустрічаються поспіль), тоді literal_text буде рядком нульової довжини. Якщо поля заміни немає, значення field_name, format_spec і conversion будуть None.

get_field(field_name, args, kwargs)

Враховуючи field_name, яке повертає parse() (див. вище), конвертуйте його в об’єкт для форматування. Повертає кортеж (obj, used_key). Версія за замовчуванням приймає рядки у формі, визначеній у PEP 3101, як-от «0[name]» або «label.title». args і kwargs передаються до vformat(). Повернене значення used_key має те саме значення, що й параметр key для get_value().

get_value(key, args, kwargs)

Отримати вказане значення поля. Аргумент key буде цілим числом або рядком. Якщо це ціле число, воно представляє індекс позиційного аргументу в args; якщо це рядок, то він представляє іменований аргумент у kwargs.

Параметр args встановлюється на список позиційних аргументів vformat(), а параметр kwargs встановлюється на словник ключових аргументів.

Для складених імен полів ці функції викликаються лише для першого компонента імені поля; подальші компоненти обробляються через звичайні операції атрибутів та індексування.

Так, наприклад, вираз поля «0.name» призведе до виклику get_value() з аргументом key 0. Атрибут name шукатиметься після get_value() повертається шляхом виклику вбудованої функції getattr().

Якщо індекс або ключове слово посилається на елемент, який не існує, тоді має бути викликана IndexError або KeyError.

check_unused_args(used_args, args, kwargs)

За потреби реалізуйте перевірку невикористаних аргументів. Аргументи цієї функції — це набір усіх ключів аргументів, на які фактично посилається рядок формату (цілі числа для позиційних аргументів і рядки для іменованих аргументів), а також посилання на args і kwargs, передане до vformat. Набір невикористаних аргументів можна обчислити за цими параметрами. Припускається, що check_unused_args() викликає виключення, якщо перевірка не вдається.

format_field(value, format_spec)

format_field() просто викликає глобальний вбудований format(). Метод надається для того, щоб підкласи могли його замінити.

convert_field(value, conversion)

Перетворює значення (повернуте get_field()) із заданим типом перетворення (як у кортежі, поверненому методом parse()). Версія за замовчуванням підтримує типи перетворення „s“ (str), „r“ (repr) і „a“ (ascii).

Синтаксис рядка формату

Метод str.format() і клас Formatter мають однаковий синтаксис для рядків форматування (хоча у випадку Formatter підкласи можуть визначати власний синтаксис рядків форматування). Синтаксис подібний до синтаксису форматованих рядкових літералів, але він менш складний і, зокрема, не підтримує довільні вирази.

Рядки формату містять «поля заміни», оточені фігурними дужками {}. Все, що не міститься в фігурних дужках, вважається буквальним текстом, який копіюється без змін у вивід. Якщо вам потрібно включити фігурну дужку в буквальний текст, її можна екранувати подвоєнням: {{ і }}.

Граматика поля заміни така:

replacement_field ::=  "{" [field_name] ["!" conversion] [":" format_spec] "}"
field_name        ::=  arg_name ("." attribute_name | "[" element_index "]")*
arg_name          ::=  [identifier | digit+]
attribute_name    ::=  identifier
element_index     ::=  digit+ | index_string
index_string      ::=  <any source character except "]"> +
conversion        ::=  "r" | "s" | "a"
format_spec       ::=  format-spec:format_spec

Якщо говорити менш формально, то поле заміни може починатися з field_name, яке визначає об’єкт, значення якого має бути відформатовано та вставлено у вихідні дані замість поля заміни. За field_name необов’язково йде поле conversion, якому передує знак оклику '!', і format_spec, якому передує двокрапка ':''. Вони вказують нестандартний формат для значення заміни.

Дивіться також розділ Міні-мова специфікації формату.

The field_name itself begins with an arg_name that is either a number or a keyword. If it’s a number, it refers to a positional argument, and if it’s a keyword, it refers to a named keyword argument. An arg_name is treated as a number if a call to str.isdecimal() on the string would return true. If the numerical arg_names in a format string are 0, 1, 2, … in sequence, they can all be omitted (not just some) and the numbers 0, 1, 2, … will be automatically inserted in that order. Because arg_name is not quote-delimited, it is not possible to specify arbitrary dictionary keys (e.g., the strings '10' or ':-]') within a format string. The arg_name can be followed by any number of index or attribute expressions. An expression of the form '.name' selects the named attribute using getattr(), while an expression of the form '[index]' does an index lookup using __getitem__().

Змінено в версії 3.1: Специфікатори позиційного аргументу можна опустити для str.format(), тому '{} {}'.format(a, b) еквівалентний '{0} {1}'.format (а, б).

Змінено в версії 3.4: Специфікатори позиційного аргументу можна опустити для Formatter.

Кілька простих прикладів рядків форматування:

"First, thou shalt count to {0}"  # References first positional argument
"Bring me a {}"                   # Implicitly references the first positional argument
"From {} to {}"                   # Same as "From {0} to {1}"
"My quest is {name}"              # References keyword argument 'name'
"Weight in tons {0.weight}"       # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}"   # First element of keyword argument 'players'.

The conversion field causes a type coercion before formatting. Normally, the job of formatting a value is done by the __format__() method of the value itself. However, in some cases it is desirable to force a type to be formatted as a string, overriding its own definition of formatting. By converting the value to a string before calling __format__(), the normal formatting logic is bypassed.

Наразі підтримуються три позначки перетворення: '!s', який викликає str() для значення, ''!r', який викликає repr() та '!a' , який викликає ascii().

Деякі приклади:

"Harold's a clever {0!s}"        # Calls str() on the argument first
"Bring out the holy {name!r}"    # Calls repr() on the argument first
"More {!a}"                      # Calls ascii() on the argument first

Поле format_spec містить специфікацію того, як має бути представлене значення, включаючи такі деталі, як ширина поля, вирівнювання, відступ, десяткова точність тощо. Кожен тип значення може визначати власну «міні-мову форматування» або інтерпретацію format_spec.

Більшість вбудованих типів підтримують загальну міні-мову форматування, яка описана в наступному розділі.

Поле format_spec також може містити вкладені поля заміни. Ці вкладені поля заміни можуть містити назву поля, позначку перетворення та специфікацію формату, але глибше вкладення не допускається. Поля заміни в format_spec замінюються перед інтерпретацією рядка format_spec. Це дозволяє динамічно вказувати форматування значення.

Перегляньте розділ Приклади форматування для деяких прикладів.

Міні-мова специфікації формату

«Специфікації формату» використовуються в полях заміни, що містяться в рядку формату, щоб визначити, як подаються окремі значення (див. Синтаксис рядка формату і f-strings). Їх також можна передати безпосередньо до вбудованої функції format(). Кожен форматований тип може визначати, як слід інтерпретувати специфікацію формату.

Більшість вбудованих типів реалізують такі параметри специфікацій формату, хоча деякі параметри форматування підтримуються лише числовими типами.

Загальна домовленість полягає в тому, що порожня специфікація формату дає такий самий результат, як якщо б ви викликали str() для значення. Непорожня специфікація формату зазвичай змінює результат.

Загальна форма специфікатора стандартного формату така:

format_spec     ::=  [[fill]align][sign]["z"]["#"]["0"][width][grouping_option]["." precision][type]
fill            ::=  <any character>
align           ::=  "<" | ">" | "=" | "^"
sign            ::=  "+" | "-" | " "
width           ::=  digit+
grouping_option ::=  "_" | ","
precision       ::=  digit+
type            ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"

Якщо вказано дійсне значення align, йому може передувати символ fill, який може бути будь-яким символом і за замовчуванням є пробілом, якщо його опустити. Неможливо використовувати літеральну фігурну дужку (»{» або «}») як символ fill у відформатованому рядковому літералі або під час використання метод str.format(). Однак можна вставити фігурну дужку з вкладеним полем заміни. Це обмеження не впливає на функцію format().

Значення різних параметрів вирівнювання таке:

Варіант	Значення
'<'	Примусово вирівнює поле за лівим краєм у межах доступного простору (це типове значення для більшості об’єктів).
'>'	Примусово вирівнює поле за правим краєм у межах доступного простору (це типове значення для чисел).
'='	Forces the padding to be placed after the sign (if any) but before the digits. This is used for printing fields in the form „+000000120“. This alignment option is only valid for numeric types, excluding complex. It becomes the default for numbers when „0“ immediately precedes the field width.
'^'	Примусово центрує поле в межах доступного простору.

Зауважте, що якщо не визначено мінімальну ширину поля, ширина поля завжди матиме той самий розмір, що й дані для його заповнення, тому параметр вирівнювання не має значення в цьому випадку.

Параметр знак дійсний лише для типів чисел і може бути одним із таких:

Варіант	Значення
'+'	вказує на те, що знак слід використовувати як для додатних, так і для від’ємних чисел.
'-'	вказує, що знак слід використовувати лише для від’ємних чисел (це типова поведінка).
простір	вказує на те, що для додатних чисел слід використовувати пробіл, а для від’ємних – знак мінус.

The 'z' option coerces negative zero floating-point values to positive zero after rounding to the format precision. This option is only valid for floating-point presentation types.

Змінено в версії 3.11: Added the 'z' option (see also PEP 682).

Опція '#' спричиняє використання «альтернативної форми» для перетворення. Альтернативна форма визначається по-різному для різних типів. Цей параметр дійсний лише для цілих чисел, типів із плаваючою точкою та складних типів. Для цілих чисел, коли використовується двійковий, вісімковий або шістнадцятковий вивід, цей параметр додає відповідний префікс '0b', '0o', '0x' або '0X' до вихідного значення. Для float і complex альтернативна форма призводить до того, що результат перетворення завжди міститиме символ десяткової коми, навіть якщо за ним не йде жодна цифра. Зазвичай символ десяткової коми з’являється в результаті цих перетворень, лише якщо за ним стоїть цифра. Крім того, для перетворень 'g' і 'G'' кінцеві нулі не видаляються з результату.

The ',' option signals the use of a comma for a thousands separator for floating-point presentation types and for integer presentation type 'd'. For other presentation types, this option is an error. For a locale aware separator, use the 'n' integer presentation type instead.

Змінено в версії 3.1: Додано параметр ','' (див. також PEP 378).

The '_' option signals the use of an underscore for a thousands separator for floating-point presentation types and for integer presentation type 'd'. For integer presentation types 'b', 'o', 'x', and 'X', underscores will be inserted every 4 digits. For other presentation types, specifying this option is an error.

Змінено в версії 3.6: Додано параметр '_' (див. також PEP 515).

ширина — це десяткове ціле число, що визначає мінімальну загальну ширину поля, включаючи будь-які префікси, роздільники та інші символи форматування. Якщо не вказано, ширина поля визначатиметься вмістом.

When no explicit alignment is given, preceding the width field by a zero ('0') character enables sign-aware zero-padding for numeric types, excluding complex. This is equivalent to a fill character of '0' with an alignment type of '='.

Змінено в версії 3.10: Попереднє поле width '0' більше не впливає на стандартне вирівнювання для рядків.

Точність — це десяткове ціле число, яке вказує, скільки цифр має відображатися після коми для типів подання 'f' і 'F' або перед і після десяткової коми для типів подання 'g' або 'G''. Для типів представлення рядків поле вказує максимальний розмір поля - іншими словами, скільки символів буде використано з вмісту поля. Точність не допускається для цілочисельних типів подання.

Нарешті, тип визначає, як мають бути представлені дані.

Доступні типи подання рядків:

Тип	Значення
's''	Формат рядка. Це типовий тип для рядків, і його можна опустити.
Жодного	Те саме, що 's.

Доступні типи представлення цілих чисел:

Тип	Значення
'b''	Двійковий формат. Виводить число за основою 2.
'c''	характер. Перетворює ціле число на відповідний символ Юнікоду перед друком.
'd''	Десяткове ціле число. Виводить число за основою 10.
'o'	Вісімковий формат. Виводить число за основою 8.
'x''	Шістнадцятковий формат. Виводить число за основою 16, використовуючи малі літери для цифр над 9.
'X''	Шістнадцятковий формат. Виводить число за основою 16, використовуючи літери верхнього регістру для цифр над 9. Якщо вказано '#', префікс '0x' буде написаний у верхньому регістрі до '0X' також.
'n'	Номер. Це те саме, що 'd'', за винятком того, що він використовує поточні параметри мови для вставки відповідних символів-роздільників чисел.
Жодного	Те саме, що 'd'.

In addition to the above presentation types, integers can be formatted with the floating-point presentation types listed below (except 'n' and None). When doing so, float() is used to convert the integer to a floating-point number before formatting.

Доступні типи представлення значень float і Decimal:

Тип	Значення
'e''	Scientific notation. For a given precision p, formats the number in scientific notation with the letter „e“ separating the coefficient from the exponent. The coefficient has one digit before and p digits after the decimal point, for a total of p + 1 significant digits. With no precision given, uses a precision of 6 digits after the decimal point for float, and shows all coefficient digits for Decimal. If p=0, the decimal point is omitted unless the # option is used.
'E'	Наукова нотація. Те саме, що 'e', за винятком того, що він використовує верхній регістр „E“ як символ роздільника.
'f''	Fixed-point notation. For a given precision p, formats the number as a decimal number with exactly p digits following the decimal point. With no precision given, uses a precision of 6 digits after the decimal point for float, and uses a precision large enough to show all coefficient digits for Decimal. If p=0, the decimal point is omitted unless the # option is used.
'F''	Позначення з фіксованою комою. Те саме, що 'f, але перетворює nan на NAN і inf на INF.
'g''	Загальний формат. Для заданої точності p >= 1 це округлює число до p значущих цифр, а потім форматує результат або у форматі з фіксованою комою, або в науковому позначенні, залежно від його величини. Точність 0 розглядається як еквівалентна точності 1. Точні правила такі: припустимо, що результат, відформатований із типом представлення 'e' і точністю p-1, матиме показник exp. Тоді, якщо m <= exp < p, where m is -4 for floats and -6 for Decimals, число форматується з типом представлення 'f' і точністю p-1-exp. В іншому випадку число форматується з типом представлення 'e і точністю p-1. В обох випадках незначущі кінцеві нулі видаляються зі значущого, а десяткова кома також видаляється, якщо після неї не залишилося цифр, якщо не використовується опція '#'. Без заданої точності, використовує точність 6 значущих цифр для float. Для Decimal коефіцієнт результату формується з цифр коефіцієнта значення; наукова нотація використовується для значень, менших за 1e-6 в абсолютному значенні, і значень, де розрядне значення молодшої значущої цифри більше 1, а в інших випадках використовується нотація з фіксованою комою. Позитивна і негативна нескінченність, позитивний і негативний нуль і nans форматуються як inf, -inf, 0, -0 і nan відповідно, незалежно точності.
'G''	Загальний формат. Те саме, що 'g', за винятком переключення на 'E', якщо число стає завеликим. Представлення нескінченності та NaN також написані у верхньому регістрі.
'n'	Номер. Це те саме, що 'g'', за винятком того, що він використовує поточні налаштування мови для вставки відповідних символів-роздільників чисел.
'%'	Відсоток. Множить число на 100 і відображає у фіксованому форматі ('f') із знаком відсотка.
Жодного	For float this is like the 'g' type, except that when fixed-point notation is used to format the result, it always includes at least one digit past the decimal point, and switches to the scientific notation when exp >= p - 1. When the precision is not specified, the latter will be as large as needed to represent the given value faithfully. Для Decimal це те саме, що 'g' або 'G' залежно від значення context.capitals для поточного десяткового контексту. Загальним ефектом є відповідність виводу str(), зміненого іншими модифікаторами формату.

The result should be correctly rounded to a given precision p of digits after the decimal point. The rounding mode for float matches that of the round() builtin. For Decimal, the rounding mode of the current context will be used.

The available presentation types for complex are the same as those for float ('%' is not allowed). Both the real and imaginary components of a complex number are formatted as floating-point numbers, according to the specified presentation type. They are separated by the mandatory sign of the imaginary part, the latter being terminated by a j suffix. If the presentation type is missing, the result will match the output of str() (complex numbers with a non-zero real part are also surrounded by parentheses), possibly altered by other format modifiers.

Приклади форматування

Цей розділ містить приклади синтаксису str.format() і порівняння зі старим %-форматуванням.

У більшості випадків синтаксис подібний до старого %-форматування, з додаванням {} і використанням : замість %. Наприклад, '%03.2f'' можна перекласти на '{:03.2f}''.

Новий синтаксис формату також підтримує нові та різні параметри, показані в наступних прикладах.

Доступ до аргументів за позицією:

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
'abracadabra'

Доступ до аргументів за назвою:

>>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
'Coordinates: 37.24N, -115.81W'
>>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
>>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
'Coordinates: 37.24N, -115.81W'

Доступ до атрибутів аргументів:

>>> c = 3-5j
>>> ('The complex number {0} is formed from the real part {0.real} '
...  'and the imaginary part {0.imag}.').format(c)
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
>>> class Point:
...     def __init__(self, x, y):
...         self.x, self.y = x, y
...     def __str__(self):
...         return 'Point({self.x}, {self.y})'.format(self=self)
...
>>> str(Point(4, 2))
'Point(4, 2)'

Доступ до елементів аргументів:

>>> coord = (3, 5)
>>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
'X: 3;  Y: 5'

Заміна %s та %r:

>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"

Вирівнювання тексту та визначення ширини:

>>> '{:<30}'.format('left aligned')
'left aligned                  '
>>> '{:>30}'.format('right aligned')
'                 right aligned'
>>> '{:^30}'.format('centered')
'           centered           '
>>> '{:*^30}'.format('centered')  # use '*' as a fill char
'***********centered***********'

Заміна %+f, %-f і % f та вказівка знака:

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
'3.140000; -3.140000'

Заміна %x і %o і перетворення значення на різні бази:

>>> # format also supports binary numbers
>>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # with 0x, 0o, or 0b as prefix:
>>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

Використання коми як роздільника тисяч:

>>> '{:,}'.format(1234567890)
'1,234,567,890'

Вираз у відсотках:

>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 86.36%'

Використання спеціального форматування:

>>> import datetime
>>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
>>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
'2010-07-04 12:15:58'

Вкладені аргументи та більш складні приклади:

>>> for align, text in zip('<^>', ['left', 'center', 'right']):
...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
...
'left<<<<<<<<<<<<'
'^^^^^center^^^^^'
'>>>>>>>>>>>right'
>>>
>>> octets = [192, 168, 0, 1]
>>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
'C0A80001'
>>> int(_, 16)
3232235521
>>>
>>> width = 5
>>> for num in range(5,12): 
...     for base in 'dXob':
...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
...     print()
...
    5     5     5   101
    6     6     6   110
    7     7     7   111
    8     8    10  1000
    9     9    11  1001
   10     A    12  1010
   11     B    13  1011

Рядки шаблону

Template strings provide simpler string substitutions as described in PEP 292. A primary use case for template strings is for internationalization (i18n) since in that context, the simpler syntax and functionality makes it easier to translate than other built-in string formatting facilities in Python. As an example of a library built on template strings for i18n, see the flufl.i18n package.

Рядки шаблону підтримують заміни на основі $ за такими правилами:

• $$ є екрануванням; він замінюється одним $.

• $identifier називає покажчик місця заповнення, що відповідає ключу відображення "identifier". За замовчуванням "ідентифікатор" обмежується будь-яким незалежним від регістру алфавітно-цифровим рядком ASCII (включаючи підкреслення), який починається з підкреслення або літери ASCII. Перший неідентифікаційний символ після символу $ завершує цю специфікацію заповнювача.

• ${identifier} еквівалентний $identifier. Він потрібен, якщо дійсні символи ідентифікатора слідують за заповнювачем, але не є частиною заповнювача, наприклад "${noun}ification".

Будь-яка інша поява $ у рядку призведе до появи ValueError.

Модуль string надає клас Template, який реалізує ці правила. Методи Template:

class string.Template(template)

Конструктор приймає один аргумент, який є рядком шаблону.

substitute(mapping={}, /, **kwds)

Виконує підстановку шаблону, повертаючи новий рядок. mapping — це будь-який словниковий об’єкт із ключами, які відповідають заповнювачам у шаблоні. Крім того, ви можете надати аргументи ключових слів, де ключові слова є заповнювачами. Якщо вказано як mapping, так і kwds і є дублікати, заповнювачі з kwds мають пріоритет.

safe_substitute(mapping={}, /, **kwds)

Подібно до substitute(), за винятком того, що якщо заповнювачі відсутні в mapping і kwds, замість виклику винятку KeyError, вихідний заповнювач відображатиметься в кінцевому рядку без змін. Крім того, на відміну від substitute(), будь-яка інша поява $ просто повертатиме $ замість того, щоб викликати ValueError.

Хоча інші винятки все ще можуть виникати, цей метод називається «безпечним», оскільки він завжди намагається повернути придатний для використання рядок замість того, щоб викликати виняток. З іншого боку, safe_substitute() може бути будь-чим іншим, ніж безпечним, оскільки він мовчки ігноруватиме неправильні шаблони, що містять висячі розділювачі, невідповідні фігурні дужки або заповнювачі, які не є дійсними ідентифікаторами Python.

is_valid()

Returns false if the template has invalid placeholders that will cause substitute() to raise ValueError.

Added in version 3.11.

get_identifiers()

Returns a list of the valid identifiers in the template, in the order they first appear, ignoring any invalid identifiers.

Added in version 3.11.

Екземпляри Template також надають один публічний атрибут даних:

template

Це об’єкт, переданий аргументу template конструктора. Загалом, вам не слід змінювати його, але доступ лише для читання не застосовується.

Ось приклад використання шаблону:

>>> from string import Template
>>> s = Template('$who likes $what')
>>> s.substitute(who='tim', what='kung pao')
'tim likes kung pao'
>>> d = dict(who='tim')
>>> Template('Give $who $100').substitute(d)
Traceback (most recent call last):
...
ValueError: Invalid placeholder in string: line 1, col 11
>>> Template('$who likes $what').substitute(d)
Traceback (most recent call last):
...
KeyError: 'what'
>>> Template('$who likes $what').safe_substitute(d)
'tim likes $what'

Розширене використання: ви можете створити підкласи Template, щоб налаштувати синтаксис заповнювача, символ роздільника або весь регулярний вираз, який використовується для аналізу рядків шаблону. Для цього ви можете змінити ці атрибути класу:

• розділювач – це літеральний рядок, що описує заповнювач, що вводить розділювач. Значення за замовчуванням – $. Зауважте, що це не повинен бути регулярний вираз, оскільки реалізація викличе re.escape() для цього рядка за потреби. Крім того, зауважте, що ви не можете змінити роздільник після створення класу (тобто інший роздільник має бути встановлено в просторі імен класу підкласу).

• idpattern – це регулярний вираз, що описує шаблон для заповнювачів без дужок. Стандартним значенням є регулярний вираз (?a:[_a-z][_a-z0-9]*). Якщо це задано і braceidpattern має значення None, цей шаблон також застосовуватиметься до заповнювачів у дужках.

  Примітка

  Оскільки типовими прапорцями є re.IGNORECASE, шаблон [a-z] може збігатися з деякими символами, відмінними від ASCII. Ось чому ми використовуємо місцевий прапор a тут.

  Змінено в версії 3.7: braceidpattern можна використовувати для визначення окремих шаблонів, що використовуються всередині та поза дужками.

• braceidpattern – Це схоже на idpattern, але описує шаблон для заповнювачів у дужках. За замовчуванням встановлено None, що означає повернення до idpattern (тобто той самий шаблон використовується як усередині, так і ззовні дужок). Якщо дано, це дозволяє визначати різні шаблони для заповнювачів у дужках і без дужок.

  Added in version 3.7.

• flags – прапорці регулярного виразу, які будуть застосовані під час компіляції регулярного виразу, що використовується для розпізнавання підстановок. Значення за замовчуванням – re.IGNORECASE. Зауважте, що re.VERBOSE завжди додаватиметься до прапорців, тому спеціальні idpatternмають відповідати угодам для докладних регулярних виразів.

  Added in version 3.2.

Крім того, ви можете надати повний шаблон регулярного виразу, перевизначивши атрибут класу pattern. Якщо ви це зробите, значення має бути об’єктом регулярного виразу з чотирма іменованими групами захоплення. Групи захоплення відповідають правилам, наведеним вище, а також правилу недійсних заповнювачів:

• escaped – ця група відповідає escape-послідовності, напр. $$, у шаблоні за замовчуванням.

• named – ця група відповідає імені заповнювача без дужок; він не повинен містити роздільник у групі захоплення.

• в дужках – ця група відповідає імені заповнювача в дужках; він не повинен включати ні роздільник, ні дужки в групу захоплення.

• invalid – ця група відповідає будь-якому іншому шаблону розділювача (зазвичай один роздільник), і вона має з’являтися останньою в регулярному виразі.

The methods on this class will raise ValueError if the pattern matches the template without one of these named groups matching.

Допоміжні функції

string.capwords(s, sep=None)

Розділіть аргумент на слова за допомогою str.split(), кожне слово з великої літери за допомогою str.capitalize() і об’єднайте слова з великої літери за допомогою str.join(). Якщо необов’язковий другий аргумент sep відсутній або None, ряди пробілів замінюються одним пробілом, а пробіли на початку та в кінці видаляються, інакше sep використовується для розділення та об’єднання слів.