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

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

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

6.1.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).

get_value(key, args, kwargs)

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

check_unused_args(used_args, args, kwargs)

Реализует проверку неиспользованных аргументов, если это необходимо.

format_field(value, format_spec)

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

convert_field(value, conversion)

Преобразует значение (возвращённое get_field()), учитывая тип преобразования (как в кортеже, возвращаемом методом parse()).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Строки шаблонов обеспечивают более простой замену строк, как описано в PEP 292. Основное применение строк шаблонов — для интернационализации (i18n), так как в этом контексте более простой синтаксис и функциональность облегчают перевод по сравнению с другими встроенными средствами форматирования строк в Python. В качестве примера библиотеки, построенной на строках шаблонов для i18n, см. пакет flufl.i18n.

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

• $$ — это символ экранирования; он заменяется на один $.
• $identifier — это имя заполнитель замены, соответствующее ключу отображения "identifier". По умолчанию "identifier" ограничено любыми регистронезависимыми строчными ASCII буквенно-цифровыми строками (включая нижние подчеркивания), начинающимися с нижнего подчеркивания или ASCII буквы. Первый символ, не являющийся идентификатором, после символа $ завершает это задание спецификации заполнителя.
• ${identifier} эквивалентно $identifier . Требуется, когда за заполнителем следуют допустимые символы идентификатора, которые не являются частью заполнителя, например "${noun}ification".

Любое другое появление $ в строке приведет к возбуждению ValueError.

Модуль string предоставляет класс Template, который реализует эти правила. Методы Template:

class string.Template(template)

Конструктор принимает единственный аргумент, который является строкой шаблона.

substitute(mapping, **kwds)

Выполняет подстановку в шаблоне, возвращая новую строку. mapping — это любой объект типа словаря с ключами, соответствующими заполнителям в шаблоне. В качестве альтернативы вы можете предоставить именованные аргументы, где именованные аргументы соответствуют заполнителям. Если заданы как mapping, так и kwds, и есть дубликаты, заполнители из kwds имеют приоритет.

safe_substitute(mapping, **kwds)

Аналогично substitute(), за исключением того, что если заполнители отсутствуют в mapping и kwds, вместо генерации исключения KeyError, исходный заполнитель останется в результирующей строке без изменений. Кроме того, в отличие от substitute(), любые другие вхождения $ просто вернут $ вместо генерации исключения ValueError.

Хотя могут возникнуть и другие исключения, этот метод называется «безопасным», потому что он всегда пытается вернуть используемую строку вместо генерации исключения. В другом смысле, safe_substitute() может быть чем угодно, кроме безопасного, поскольку он будет молча игнорировать неправильно сформированные шаблоны, содержащие висящие разделители, несоответствующие фигурные скобки или заполнители, которые не являются допустимыми идентификаторами Python.

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

template

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

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

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

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

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

• idpattern – Это регулярное выражение, описывающее шаблон для заполнителей без фигурных скобок (фигурные скобки будут автоматически добавлены в соответствии с требованиями). Значение по умолчанию — регулярное выражение (?-i:[_a-zA-Z][_a-zA-Z0-9]*).

  Примечание

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

  Хотя flags сохраняется в значении re.IGNORECASE для обратной совместимости, при создании подклассов его можно переопределить на 0 или re.IGNORECASE | re.ASCII.

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

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

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

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

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

string.capwords(s, sep=None)

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