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

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

1. Константы строк

Определённые в этом модуле константы:

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

2. Форматирование строк

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

class string.Formatter

Класс Formatter имеет следующие публичные методы:

format(format_string, *args, **kwargs)

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

Устарело начиная с версии 3.5: Передача строки формата в качестве ключевого аргумента format_string устарела.

vformat(format_string, args, kwargs)

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

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

parse(format_string)

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

get_field(field_name, args, kwargs)

Принимая field_name, возвращённый parse() (см. выше), преобразовать его в объект для форматирования. Возвращает кортеж (obj, used_key). По умолчанию версия принимает строки, определённые в PEP 3101, такие как “0[name]” или “label.title”. args и kwargs передаются в vformat().

get_value(key, args, kwargs)

Возвращает значение указанного поля. Аргумент key будет либо целым числом, либо строкой. Если это целое число, оно представляет индекс позиционного аргумента в args; если это строка, то она представляет именованный аргумент в kwargs.

check_unused_args(used_args, args, kwargs)

Реализуйте проверку на неиспользуемые аргументы, если это необходимо. Аргументы этой функции — множество всех ключей аргументов, которые фактически упоминались в строке формата (целые числа для позиционных аргументов и строки для именованных аргументов), а также ссылка на args и kwargs, которые были переданы в vformat. Множество неиспользуемых аргументов может быть вычислено из этих параметров.

format_field(value, format_spec)

format_field() просто вызывает глобальную встроенную функцию format().

convert_field(value, conversion)

Преобразует значение (возвращённое get_field()) с заданным типом преобразования (как в кортеже, возвращаемом методом parse()). По умолчанию версия понимает типы преобразования ‘s’ (str), ‘r’ (repr) и ‘a’ (ascii).

3. Синтаксис строки формата

Метод str.format() и класс Formatter используют одинаковый синтаксис для строк формата (хотя в случае с Formatter, подклассы могут определять свой собственный синтаксис строки формата).

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

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

replacement_field ::=  "{" [field_name] ["!" conversion] [":" format_spec] "}"
field_name        ::=  arg_name ("." attribute_name | "[" element_index "]")*
arg_name          ::=  [identifier | integer]
attribute_name    ::=  identifier
element_index     ::=  integer | index_string
index_string      ::=  <any source character except "]"> +
conversion        ::=  "r" | "s" | "a"
format_spec       ::=  <described in the next section>

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

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

Само имя_поля начинается с имени_аргумента, которое может быть числом или ключевым словом. Если это число, оно ссылается на позиционный аргумент, а если ключевое слово, то на именованный аргумент. Если числовые имена аргументов в строке форматирования идут последовательно 0, 1, 2, ..., то их можно опустить (не только некоторые) и числа 0, 1, 2, ... будут автоматически вставлены в этом порядке. Поскольку имя_аргумента не заключено в кавычки, невозможно указать произвольные ключи словаря (например, строки '10' или ':-]') внутри строки форматирования. За именем_аргумента могут следовать любое количество индексных или атрибутных выражений. Выражение вида '.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'.

Поле преобразования вызывает приведение типа перед форматированием. Обычно задача форматирования значения выполняется методом __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

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

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

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

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

3.1. Мини-язык спецификаций форматирования

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

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

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

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

format_spec ::=  [[fill]align][sign][#][0][width][,][.precision][type]
fill        ::=  <any character>
align       ::=  "<" | ">" | "=" | "^"
sign        ::=  "+" | "-" | " "
width       ::=  integer
precision   ::=  integer
type        ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"

Если задано допустимое значение выравнивания, перед ним может стоять символ заполнения, который может быть любым символом и по умолчанию равен пробелу, если он опущен. Невозможно использовать литеральную фигурную скобку («{» или «}») в качестве символа заполнения при использовании метода str.format(). Однако возможно вставить фигурную скобку с вложенным полем замены. Это ограничение не влияет на функцию format().

Значение различных параметров выравнивания:

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

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

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

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

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

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

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

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

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

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

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

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

3.2. Примеры формата

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

4. Строки шаблонов

Шаблоны предоставляют более простые подстановки строк, как описано в PEP 292. Вместо обычных подстановок на основе %, шаблоны поддерживают подстановки на основе $, используя следующие правила:

• $$ — это 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

Это объект, переданный аргументу 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-z][_a-z0-9]*.

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

  Введено в версии 3.2.

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

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

5. Функции-помощники

string.capwords(s, sep=None)

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