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[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 подклассы могут определять свой собственный синтаксис форматной строки). Синтаксис связан с синтаксисом 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       ::=  <described in the next section>

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

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

Само имя_поля начинается с имени_арг, которое является либо числом, либо ключевым словом. Если это число, то оно относится к позиционному аргументу, а если это ключевое слово, то оно относится к именованному аргументу ключевого слова. Если числовые имена arg_name в строке формата имеют последовательность 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][#][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.

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

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

• $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¶

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

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

>>> 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, то этот шаблон будет применяться и к скобкам.

  Примечание

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