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. Форматирование строк¶String Formatting

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

class string.Formatter¶

Класс Formatter имеет следующие открытые методы:

format(format_string, *args, **kwargs)¶

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

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, который может быть числом или ключевым словом. Если это число, оно ссылается на позиционный аргумент; если это ключевое слово – на именованный. Если числовые имена аргументов в строке формата идут подряд 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" должно быть корректным идентификатором Python. Первый символ, не являющийся идентификатором, после символа $ завершает этот спецификатор заполнителя.
• ${identifier} эквивалентно $identifier. Такая форма требуется, когда за заполнителем следуют символы, являющиеся корректными идентификаторами, но не входящие в состав заполнителя, как в "${noun}ification".

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

The string module provides a Template class that implements these rules. The methods of Template are:

class string.Template(template)¶

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

substitute(mapping, **kwds)¶

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

safe_substitute(mapping, **kwds)¶

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

Хотя другие исключения всё ещё могут возникать, этот метод называется «безопасным» (safe), потому что подстановки всегда стараются вернуть рабочую строку вместо возбуждения исключения. В другом смысле, 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, чтобы настроить синтаксис плейсхолдера, символ-разделитель или всё регулярное выражение, используемое для разбора строк шаблона. Для этого можно переопределить следующие атрибуты класса:

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

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

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

  Новое в версии 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 используется для разделения и соединения слов.