string — Общие строковые операции

Исходный код: Lib/string.py


Строковые константы

Константы, определенные в этом модуле:

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       ::=  <described in the next section>

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

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

Сам field_name начинается с arg_name, который является числом или ключевым словом. Если это число, оно относится к позиционному аргументу, а если это ключевое слово, оно относится к именованному ключевому аргументу. Если числовые arg_names в строке формата — это 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.

Примеры простых форматных строк:

"Сначала посчитай до {0}"         # Ссылки на первый позиционный аргумент
"Принеси мне {}"                  # Неявно ссылается на первый позиционный аргумент
"От {} до {}"                     # То же, что "От {0} до {1}"
"Мой квест {name}"                # Ссылка на ключевой аргумент «name»
"Масса в тоннах {0.weight}"       # атрибут «weight» первого позиционного аргумента
"Уничтожено единиц: {players[0]}" # Первый элемент ключевого аргумента «players».

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

В настоящее время поддерживаются три флага преобразования: '!s', который вызывает str() по значению, '!r', который вызывает repr(), и '!a', который вызывает ascii().

Несколько примеров:

"Гарольд умный {0!s}"            # Сначала вызывает str() для первого аргумента
"Принесите святую {name!r}"      # Сначала вызывает repr() для первого аргумента
"Больше {!a}"                    # Сначала вызывает ascii() для первого аргумента

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

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

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

См. несколько примеров в разделе Примеры форматов.

Спецификация формата Мини-языка

«Спецификации формата» используются в полях замены, содержащихся в строке формата, для определения того, как представлены отдельные значения (см. Синтаксис строки формата и Форматированные строковые литералы). Их также можно передать напрямую встроенной функции format(). Каждый тип таблицы форматирования может определять способ интерпретации спецификации формата.

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

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

Общая форма спецификатора стандартного формата :

format_spec     ::=  [[fill]align][sign][#][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().

Смысл различных вариантов выравнивания следующий:

Опция Значение
'<' Заставляет поле выравниваться по левому краю в пределах доступного пространства (это значение по умолчанию для большинства объектов).
'>' Заставляет поле выравниваться по правому краю в доступном пространстве (это значение по умолчанию для чисел).
'=' Принудительно помещает заполнение после знака (если имеется), но перед цифрами. Используется для печати полей в форме «+000000120». Параметр выравнивания допустим только для числовых типов. Он становится значением по умолчанию, когда «0» сразу предшествует ширине поля.
'^' Принудительное центрирование поля в пределах доступного пространства.

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

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

Опция Значение
'+' указывает, что знак должен использоваться как для положительных, так и для отрицательных чисел.
'-' указывает, что знак должен использоваться только для отрицательных чисел (это поведение по умолчанию).
пробел указывает, что ведущий пробел должен использоваться на положительных числах, а знак минус на отрицательных числах.

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

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

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

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

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

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

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

precision — это десятичное число, указывающее, сколько цифр должно отображаться после десятичной точки для значения с плавающей запятой, отформатированного с помощью 'f' и 'F', или до и после десятичной точки для значения с плавающей запятой, отформатированного с помощью 'g' или 'G'. Для нечисловых типов поле указывает максимальный размер поля — другими словами, сколько символов будет использовано из содержимого поля. precision не допускается для целочисленных значений.

Наконец, type определяет, как данные должны быть представлены.

Доступные типы представления строк:

Тип Значение
's' Строковый формат. Является типом по умолчанию для строки и может быть пропущен.
None То же, что и 's'.

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

Тип Значение
'b' Двоичный формат. Выводит число по основанию 2.
'c' Символ. Преобразует целое число в соответствующее символ Юникода перед печатью.
'd' Десятичное целое число. Выводит число по основанию 10.
'o' Октальный формат. Выводит число по основанию 8.
'x' Шестнадцатеричный формат. Выводит число по основанию 16, используя строчные буквы для цифр больше 9.
'X' Шестнадцатеричный формат. Выводит число по основанию 16, используя прописные буквы для цифр выше 9.
'n' Число. Это то же самое, что и 'd', за исключением того, что для вставки соответствующих символов-разделителей номеров используется текущий параметр локали.
None То же, что и 'd'.

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

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

Тип Значение
'e' Научная нотация. Для заданной точности p форматирует число в экспоненциальном представлении с буквой «e», отделяющей p цифр коэффициента от экспоненты. Коэффициент состоит из одной цифры перед и после десятичной точки, всего p + 1 значащих цифр. Если точность не указана, используется точность 6 цифр после десятичной точки для float и отображаются все цифры коэффициентов для Decimal. Если после десятичной точки нет цифр, десятичная точка также удаляется, если не используется опция #.
'E' Научная нотация. То же, что и 'e', за исключением того, что в качестве символа-разделителя используется заглавная буква «E».
'f' Запись с фиксированной точкой. Для заданной точности p форматирует число как десятичное с точностью p цифр после десятичной точки. Если точность не указана, используется точность 6 цифр после десятичной точки для float и используется точность, достаточно большая для отображения всех цифр коэффициентов для Decimal. Если после десятичной точки нет цифр, десятичная точка также удаляется, если не используется опция #.
'F' Представление с фиксированной точкой. То же, что и 'f', но преобразует nan в NAN и inf в INF.
'g'

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

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

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

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

'G' Общий формат. То же, что и 'g', за исключением переключения на 'E', если число становится слишком большим. Представления бесконечности и NaN также в верхнем регистре.
'n' Номер. Это то же самое, что и 'g', за исключением того, что он использует текущую настройку локали для вставки соответствующих символов разделителя чисел.
'%' Процент. Умножает число на 100 и отображает в фиксированном ('f') формате, за которым следует знак процента.
None

Для 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+ только
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc')      # распаковка последовательности аргументов
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # индексы аргументов могут повторяться
'abracadabra'

Доступ к аргументам по имени:

>>> 'Координаты: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
'Координаты: 37.24N, -115.81W'
>>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
>>> 'Координаты: {latitude}, {longitude}'.format(**coord)
'Координаты: 37.24N, -115.81W'

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

>>> c = 3-5j
>>> ('Комплексное число {0} формируется из реальной части {0.real} '
...  'и мнимой части {0.imag}.').format(c)
'Комплексное число (3-5j) формируется из реальной части 3.0 и мнимой части -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() показывает каычки: {!r}; str() нет: {!s}".format('test1', 'test2')
"repr() показывает каычки: 'test1'; str() нет: test2"

Выравнивание текста и указание ширины:

>>> '{:<30}'.format('left aligned')
'left aligned                  '
>>> '{:>30}'.format('right aligned')
'                 right aligned'
>>> '{:^30}'.format('centered')
'           centered           '
>>> '{:*^30}'.format('centered')  # используйте '*' в качестве символа заполнения
'***********centered***********'

Замена %+f, %-f и % f и указание знака:

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # показывать это всегда
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # показать пробел для положительных чисел
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # показывать только минус-то же самое, что '{:f}; {:f}'
'3.140000; -3.140000'

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

>>> # формат также поддерживает двоичные числа
>>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # с 0x, 0o или 0b как префикс:
>>> "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
>>> 'Правильные ответы: {:.2%}'.format(points/total)
'Правильные ответы: 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.

Экземпляры 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]*). Если это задано и braceidpattern равно None, этот шаблон также будет применяться к заполнителям в фигурных скобках.

    Примечание

    Поскольку по умолчанию flagsre.IGNORECASE, шаблон [a-z] может совпадать с некоторыми символами, отличными от ASCII. Вот почему мы используем здесь локальный флаг a.

    Изменено в версии 3.7: braceidpattern можно использовать для определения отдельных шаблонов, используемых внутри и снаружи фигурных скобок.

  • braceidpattern — аналогично idpattern, но описывает шаблон для заполнителей в фигурных скобках. По умолчанию используется None, что означает возврат к idpattern (т. е. один и тот же шаблон используется как внутри, так и за пределами фигурных скобок). Если задано, это позволяет вам определять разные шаблоны для заполнителей в скобках и без скобок.

    Добавлено в версии 3.7.

  • flags — флаги регулярного выражения, которые будут применяться при компиляции регулярного выражения, используемого для распознавания замен. Значение по умолчанию — re.IGNORECASE. Обратите внимание, что re.VERBOSE всегда будет добавляться к флагам, поэтому пользовательские idpatternы должны соответствовать соглашениям для подробных регулярных выражений.

    Добавлено в версии 3.2.

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

  • escaped — эта группа соответствует управляющей последовательности, например $$, в шаблоне по умолчанию.
  • named — эта группа соответствует имени заполнителя без ограничений; она не должна включать разделитель в группу захвата.
  • braced — эта группа соответствует имени заполнителя в фигурных скобках; в группе захвата не должно быть ни разделителя, ни фигурных скобок.
  • invalid — эта группа соответствует любому другому шаблону разделителя (обычно с одним разделителем) и должна появляться последней в регулярном выражении.

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

string.capwords(s, sep=None)

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