6.1. string – Общие операции со строками¶string – Common string operations

6.1.1. Строковые константы¶String constants

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

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. Пользовательское форматирование строк¶Custom String Formatting

Встроенный класс строк предоставляет возможность выполнять сложные замены переменных и форматирование значений с помощью метода 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)¶

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

Значения в кортеже концептуально представляют собой фрагмент литерального текста, за которым следует одно поле подстановки. Если литерального текста нет (что может произойти, когда два поля подстановки идут подряд), то literal_text будет строкой нулевой длины. Если поля подстановки нет, то значения field_name, format_spec и conversion будут равны None.

get_field(field_name, args, kwargs)¶

По заданному field_name, возвращённому 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).

6.1.3. Синтаксис строк форматирования¶Format String Syntax

Метод 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>

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

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

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

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

"First, thou shalt count to {0}"  # Ссылается на первый позиционный аргумент
"Bring me a {}"                   # Неявно ссылается на первый позиционный аргумент
"From {} to {}"                   # То же, что "From {0} to {1}"
"My quest is {name}"              # Ссылается на именованный аргумент 'name'
"Weight in tons {0.weight}"       # Атрибут 'weight' первого позиционного аргумента
"Units destroyed: {players[0]}"   # Первый элемент именованного аргумента 'players'.

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

В настоящее время поддерживаются три флага преобразования: '!s' вызывает str() для значения, '!r' вызывает repr(), и '!a' вызывает ascii().

Несколько примеров:

"Harold's a clever {0!s}"        # Сначала вызывает str() для аргумента
"Bring out the holy {name!r}"    # Сначала вызывает repr() для аргумента
"More {!a}"                      # Сначала вызывает ascii() для аргумента

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

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

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

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

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

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c')  # Только для версии 3.1+
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc')      # Распаковка последовательности аргументов
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # индексы аргументов могут повторяться
'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')  # использовать '*' в качестве символа заполнения
'***********centered***********'

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # отображать всегда
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # для положительных чисел отображать пробел
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # отображать только минус – то же, что и '{:f}; {:f}'
'3.140000; -3.140000'

>>> # format также поддерживает двоичные числа
>>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # с префиксом 0x, 0o или 0b:
>>> "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. Шаблонные строки¶Template strings

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

Вот пример использования 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 – эта группа соответствует любому другому шаблону разделителя (обычно одиночному разделителю), и она должна появляться последней в регулярном выражении.

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

string.capwords(s, sep=None)¶

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