string — Распространенные операции со строками¶

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

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

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[имя]» или «label.title». аргументы и 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 подклассы могут определять свой собственный синтаксис форматирования строк). Синтаксис похож на синтаксис 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

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

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

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

Несколько простых примеров строк форматирования:

"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. Это позволяет динамически задавать форматирование значения.

Некоторые примеры приведены в разделе Примеры форматирования.

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

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

>>> "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}'.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'

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

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

get_identifiers()¶

Возвращает список допустимых идентификаторов в шаблоне в том порядке, в котором они появляются первыми, игнорируя любые недопустимые идентификаторы.

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

Template экземпляры также предоставляют один атрибут общедоступных данных:

template¶

Это объект, передаваемый в аргумент template конструктора. В общем, вы не должны изменять его, но доступ только для чтения не предусмотрен.

Вот пример того, как использовать шаблон:

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

Расширенное использование: вы можете создавать подклассы Template для настройки синтаксиса заполнителя, символа-разделителя или всего регулярного выражения, используемого для анализа строк шаблона. Для этого вы можете переопределить эти атрибуты класса:

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

• idpattern - Это регулярное выражение, описывающее шаблон для заполнителей без скобок. Значением по умолчанию является регулярное выражение (?a:[_a-z][_a-z0-9]*). Если это значение задано и braceidpattern равно None, этот шаблон также будет применяться к заполнителям со скобками.

  Примечание

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

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

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

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

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

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

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

• экранированный - Эта группа соответствует escape-последовательности, например $$, в шаблоне по умолчанию.

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

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

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

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

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

string.capwords(s, sep=None)¶

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