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

Константы строк¶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-символов, которые Python считает печатаемыми. Это комбинация digits, ascii_letters, punctuation и whitespace.

Примечание

По замыслу, string.printable.isprintable() возвращает False. В частности, string.printable не является печатаемым в смысле POSIX (см. LC_CTYPE).

string.whitespace¶

Строка, содержащая все ASCII-символы, которые считаются пробельными. Включает символы: пробел, табуляция, перевод строки, возврат каретки, прогон страницы и вертикальная табуляция.

Пользовательское форматирование строк¶Custom string formatting

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

class string.Formatter¶

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

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

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

Изменено в версии 3.7: Аргумент строки форматирования теперь является только позиционным.

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

get_field(field_name, args, kwargs)¶

Имея field_name, преобразует его в форматируемый объект. Автоматическая нумерация field_name, возвращённого из parse(), выполняется с помощью vformat() перед вызовом этого метода. Возвращает кортеж (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).

Синтаксис строк форматирования¶Format string syntax

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

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

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

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:       format-spec:format_spec

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

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

Сам field_name начинается с arg_name, который может быть числом или ключевым словом. Если это число, оно ссылается на позиционный аргумент; если ключевое слово – на именованный аргумент. arg_name считается числом, если вызов str.isdecimal() для этой строки вернёт true. Если числовые 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:             [options][width_and_precision][type]
options:                 [[fill]align][sign]["z"]["#"]["0"]
fill:                    <any character>
align:                   "<" | ">" | "=" | "^"
sign:                    "+" | "-" | " "
width_and_precision:     [width_with_grouping][precision_with_grouping]
width_with_grouping:     [width][grouping]
precision_with_grouping: "." [precision][grouping] | "." grouping
width:                   digit+
precision:               digit+
grouping:                "," | "_"
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'
>>> '{:_}'.format(1234567890)
'1_234_567_890'
>>> '{:_b}'.format(1234567890)
'100_1001_1001_0110_0000_0010_1101_0010'
>>> '{:_x}'.format(1234567890)
'4996_02d2'
>>> '{:_}'.format(123456789.123456789)
'123_456_789.12345679'
>>> '{:.,}'.format(123456789.123456789)
'123456789.123,456,79'
>>> '{:,._}'.format(123456789.123456789)
'123,456,789.123_456_79'

>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 86.36%'

>>> import datetime as dt
>>> d = dt.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

Шаблонные строки ($-строки)¶Template strings ($-strings)

Шаблонные строки предоставляют более простые подстановки строк, как описано в 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.

is_valid()¶

Возвращает False, если шаблон содержит недопустимые плейсхолдеры, которые приведут к тому, что substitute() возбудит ValueError.

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

get_identifiers()¶

Возвращает список допустимых идентификаторов в шаблоне, в порядке их первого появления, игнорируя любые недопустимые идентификаторы.

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

Экземпляры 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:[_a-z][_a-z0-9]*). Если оно задано, а braceidpattern равно None, то этот шаблон будет также применяться к плейсхолдерам в скобках.

  Примечание

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

Методы этого класса возбуждают ValueError, если шаблон соответствует регулярному выражению без совпадения одной из этих именованных групп.

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

string.capwords(s, sep=None)¶

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