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