string — Обычные операции со строками

Источник: 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, которые считаются пробельными. Сюда входят символы пробела, табуляции, перевода строки, возврата, форм-фида и вертикальной табуляции.

Пользовательское форматирование строк

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

class string.Formatter

Класс Formatter имеет следующие открытые методы:

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

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

Изменено в версии 3.7: Аргумент строки формата теперь имеет значение positional-only.

vformat(format_string, args, kwargs)

Эта функция выполняет фактическую работу по форматированию. Она выделена в отдельную функцию для случаев, когда требуется передать предопределенный словарь аргументов, а не распаковывать и переупаковывать словарь как отдельные аргументы с помощью синтаксиса *args и **kwargs. vformat() выполняет работу по разбиению строки формата на символьные данные и поля замены. Она вызывает различные методы, описанные ниже.

Кроме того, в Formatter определен ряд методов, которые должны быть заменены подклассами:

parse(format_string)

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

Значения в кортеже концептуально представляют собой участок буквального текста, за которым следует одно поле замены. Если литеральный текст отсутствует (что может произойти, если два поля замены встречаются последовательно), то literal_text будет строкой нулевой длины. Если нет поля замены, то значения имя_поля, формат_спец и конверсия будут равны None.

get_field(field_name, args, kwargs)

Учитывая имя_поля, возвращенное командой parse() (см. выше), преобразуйте его в объект для форматирования. Возвращает кортеж (obj, used_key). Версия по умолчанию принимает строки формы, определенной в PEP 3101, такие как «0[name]» или «label.title». Параметры args и kwargs соответствуют параметрам, передаваемым в vformat(). Возвращаемое значение использованный_ключ имеет то же значение, что и параметр ключ в 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 подклассы могут определять свой собственный синтаксис строк форматирования). Синтаксис связан с синтаксисом formatted string literals, но он менее сложен и, в частности, не поддерживает произвольные выражения.

Строки формата содержат «поля замены», окруженные фигурными скобками {}. Все, что не заключено в скобки, считается буквальным текстом, который копируется в вывод без изменений. Если необходимо включить символ скобки в литеральный текст, его можно экранировать с помощью удвоения: {{ и }}.

Грамматика для поля замены выглядит следующим образом:

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

В менее формальных терминах поле замены может начинаться с поля имя_поля, которое указывает объект, чье значение должно быть отформатировано и вставлено в вывод вместо поля замены. За именем_поля по желанию следует поле конверсия, которому предшествует восклицательный знак '!', и формат_спецификации, которому предшествует двоеточие ':'. Они задают формат, отличный от формата по умолчанию, для значения замены.

См. также раздел Мини-язык спецификации формата.

Само имя_поля начинается с имени_арг, которое является либо числом, либо ключевым словом. Если это число, то оно относится к позиционному аргументу, а если ключевое слово, то оно относится к именованному аргументу ключевого слова. Имя arg_name считается числом, если обращение к строке str.isdecimal() вернет true. Если числовые имена arg_name в строке формата равны 0, 1, 2, … по порядку, их можно опустить все (а не только некоторые), и числа 0, 1, 2, … будут автоматически вставлены в этом порядке. Поскольку arg_name не разграничивается кавычками, в строке формата невозможно указать произвольные ключи словаря (например, строки '10' или ':-]'). За arg_name может следовать любое количество выражений индексов или атрибутов. Выражение вида '.name' выбирает именованный атрибут с помощью getattr(), а выражение вида '[index]' выполняет поиск по индексу с помощью __getitem__().

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

Изменено в версии 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'.

Поле conversion вызывает принудительное приведение типа перед форматированием. Обычно форматирование значения выполняется методом __format__() самого значения. Однако в некоторых случаях желательно заставить тип форматироваться как строка, переопределяя его собственное определение форматирования. Преобразование значения в строку перед вызовом __format__() позволяет обойти обычную логику форматирования.

В настоящее время поддерживаются три флага преобразования: '!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-струны). Они также могут быть переданы непосредственно встроенной функции format(). Каждый тип formattable может определять, как интерпретировать спецификацию формата.

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

Согласно общему соглашению, пустая спецификация формата дает такой же результат, как если бы вы вызвали 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, который может быть любым символом и по умолчанию равен пробелу, если он опущен. Невозможно использовать литеральную фигурную скобку («{» или «}») в качестве символа заполнения в formatted string literal или при использовании метода str.format(). Однако можно вставить фигурную скобку во вложенное поле замены. Это ограничение не влияет на функцию format().

Значение различных опций выравнивания следующее:

Вариант

Значение

'<'

Заставляет поле выравниваться по левому краю в пределах доступного пространства (это значение используется по умолчанию для большинства объектов).

'>'

Заставляет поле выравниваться по правому краю в пределах доступного пространства (по умолчанию для чисел).

'='

Заставляет помещать прокладку после знака (если он есть), но перед цифрами. Это используется для печати полей в форме „+000000120“. Этот параметр выравнивания действителен только для числовых типов. По умолчанию он используется для чисел, когда перед шириной поля стоит „0“.

'^'

Принудительно выравнивает поле по центру в пределах доступного пространства.

Обратите внимание, что если не задана минимальная ширина поля, то ширина поля всегда будет равна размеру заполняющих его данных, так что опция выравнивания в этом случае не имеет никакого значения.

Параметр sign действителен только для типов чисел и может быть одним из следующих:

Вариант

Значение

'+'

указывает на то, что знак должен использоваться как для положительных, так и для отрицательных чисел.

'-'

указывает, что знак должен использоваться только для отрицательных чисел (это поведение по умолчанию).

космос

указывает, что для положительных чисел следует использовать пробел, а для отрицательных - знак минус.

Опция 'z' приводит отрицательные нулевые значения с плавающей точкой к положительному нулю после округления до точности формата. Эта опция действительна только для типов представления с плавающей точкой.

Изменено в версии 3.11: Добавлена опция 'z' (см. также PEP 682).

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

Параметр ',' указывает на использование запятой в качестве разделителя тысяч. Для разделителя с учетом локали используйте вместо него целочисленный тип представления 'n'.

Изменено в версии 3.1: Добавлена опция ',' (см. также PEP 378).

Опция '_' сигнализирует об использовании подчеркивания в качестве разделителя тысяч для типов представления с плавающей запятой и для целочисленного типа представления 'd'. Для целочисленных типов представления 'b', 'o', 'x' и 'X' подчеркивание будет вставляться через каждые 4 цифры. Для других типов представления указание этого параметра является ошибкой.

Изменено в версии 3.6: Добавлена опция '_' (см. также PEP 515).

width - десятичное целое число, определяющее минимальную общую ширину поля, включая любые префиксы, разделители и другие символы форматирования. Если не указано, то ширина поля будет определяться содержимым.

Если явное выравнивание не задано, то перед полем ширина ставится нулевой символ ('0'), который обеспечивает нулевое заполнение с учетом знака для числовых типов. Это эквивалентно символу заполнения '0' с типом выравнивания '='.

Изменено в версии 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'.

Помимо перечисленных выше типов представления, целые числа могут быть отформатированы с помощью перечисленных ниже типов представления с плавающей точкой (кроме 'n' и None). При этом float() используется для преобразования целого числа в число с плавающей точкой перед форматированием.

Для значений float и Decimal доступны следующие типы представления:

Тип

Значение

'e'

Научная нотация. Для заданной точности p форматирует число в научной нотации с буквой „e“, отделяющей коэффициент от экспоненты. Коэффициент имеет одну цифру до и p цифр после десятичной точки, всего p + 1 значащих цифр. Если точность не указана, то для float используется точность 6 цифр после запятой, а для Decimal показываются все цифры коэффициента. Если после десятичной точки нет цифр, десятичная точка также удаляется, если не используется опция #.

'E'

Научная нотация. То же, что и 'e', за исключением того, что в качестве символа-разделителя используется верхний регистр „E“.

'f'

Нотация с фиксированной точкой. Для заданной точности p форматирует число как десятичное с точностью p цифр после десятичной точки. Если точность не задана, то для float используется точность 6 цифры после десятичной точки, а для Decimal - достаточно большая точность, чтобы отобразить все цифры коэффициента. Если после десятичной точки нет цифр, десятичная точка также удаляется, если не используется опция #.

'F'

Нотация с фиксированной точкой. То же, что и 'f', но преобразует nan в NAN и inf в INF.

'g'

Общий формат. Для заданной точности p >= 1 округляет число до p значащих цифр, а затем форматирует результат либо в формате с фиксированной точкой, либо в научной нотации, в зависимости от величины. Точность 0 считается эквивалентной точности 1.

Точные правила таковы: предположим, что результат, отформатированный с типом представления 'e' и точностью p-1, будет иметь экспоненту exp. Тогда, если m <= exp < p, где m - это -4 для плавающих чисел и -6 для Decimals, число форматируется с типом представления 'f' и точностью p-1-exp. В противном случае число форматируется с типом представления 'e' и точностью p-1. В обоих случаях из значащего числа удаляются незначащие нули в конце, а также удаляется десятичная точка, если после нее не осталось цифр, если только не используется опция '#'.

Если точность не задана, то для float используется точность 6 значащих цифр. Для Decimal коэффициент результата формируется из значащих цифр значения; научная нотация используется для значений, меньших 1e-6 по абсолютной величине, и значений, где значение места наименьшего значащего разряда больше 1, а в остальных случаях используется нотация с фиксированной точкой.

Положительная и отрицательная бесконечность, положительный и отрицательный ноль, а также наны форматируются как inf, -inf, 0, -0 и nan соответственно, независимо от точности.

'G'

Общий формат. Такой же, как 'g', только переключается на 'E', если число становится слишком большим. Представления бесконечности и NaN также имеют верхний регистр.

'n'

Число. Это то же самое, что и 'g', за исключением того, что для вставки соответствующих символов-разделителей чисел используется текущая настройка локали.

'%'

Процент. Умножает число на 100 и отображает его в фиксированном формате ('f'), за которым следует знак процента.

Нет

Для float это то же самое, что и для 'g', за исключением того, что если для форматирования результата используется нотация с фиксированной точкой, то она всегда включает в себя по крайней мере одну цифру после десятичной точки. Используемая точность настолько велика, насколько это необходимо для точного представления данного значения.

Для Decimal это то же самое, что и 'g' или 'G', в зависимости от значения context.capitals для текущего десятичного контекста.

Общий эффект - соответствие вывода str() измененному другими модификаторами формата.

Примеры форматов

В этом разделе приведены примеры синтаксиса 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

Шаблонные строки

Шаблонные строки обеспечивают более простые подстановки строк, как описано в PEP 292. В первую очередь шаблонные строки используются для интернационализации (i18n), поскольку в этом контексте более простой синтаксис и функциональность облегчают перевод по сравнению с другими встроенными средствами форматирования строк в Python. В качестве примера библиотеки, построенной на шаблонных строках для i18n, можно привести пакет flufl.i18n.

Строки шаблонов поддерживают подстановки на основе $, используя следующие правила:

  • $$ - это побег; он заменяется одним $.

  • $identifier называет подстановочное место, соответствующее ключу сопоставления "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()

Возвращает false, если шаблон содержит недопустимые заполнители, которые приведут к тому, что substitute() поднимет ValueError.

Added in version 3.11.

get_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, чтобы настроить синтаксис заполнителя, символ-разделитель или все регулярное выражение, используемое для разбора строк шаблона. Для этого вы можете переопределить эти атрибуты класса:

  • delimiter – Буквальная строка, описывающая вводимый разделитель. По умолчанию используется значение $. Обратите внимание, что это не должно быть регулярным выражением, так как реализация будет вызывать re.escape() для этой строки по мере необходимости. Обратите внимание, что вы не можете изменить разделитель после создания класса (т. е. другой разделитель должен быть установлен в пространстве имен класса подкласса).

  • idpattern – Это регулярное выражение, описывающее шаблон для непересекающихся заполнителей. По умолчанию используется регулярное выражение (?a:[_a-z][_a-z0-9]*). Если задано значение idpattern и 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, поэтому пользовательские idpatterns должны следовать соглашениям для многословных регулярных выражений.

    Added in version 3.2.

В качестве альтернативы вы можете предоставить весь шаблон регулярного выражения, переопределив атрибут класса pattern. В этом случае значение должно представлять собой объект регулярного выражения с четырьмя именованными группами захвата. Группы перехвата соответствуют правилам, приведенным выше, а также правилу недопустимого заполнителя:

  • escaped – Эта группа соответствует последовательности символов, например, $$, в шаблоне по умолчанию.

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

  • braced – Эта группа соответствует имени, заключенному в скобки; она не должна включать ни разделитель, ни скобки в группе захвата.

  • invalid – Эта группа соответствует любому другому шаблону с разделителем (обычно с одним разделителем), и она должна быть последней в регулярном выражении.

Методы этого класса будут поднимать ValueError, если шаблон соответствует шаблону без совпадения с одной из этих именованных групп.

Вспомогательные функции

string.capwords(s, sep=None)

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