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

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

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

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

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

Настройка форматирования строк

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

Проход по строке формата и возвращение итерируемого набора кортежей (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() (см. выше), преобразует его в объект для форматирования. Возвращает кортеж (объект, используемый_ключ). Стандартная версия принимает строки в формате, определённом в PEP 3101, такие как «0[имя]» или «метка.заглавные». args и kwargs передаются в vformat(). Возвращаемое значение used_key имеет то же значение, что и параметр key в get_value().

get_value(key, args, kwargs)

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

Параметр args устанавливается в список позиционных аргументов для vformat(), а параметр kwargs — в словарь ключевых аргументов.

Для составных имён полей эти функции вызываются только для первой компоненты имени поля; последующие компоненты обрабатываются через обычные атрибуты и операции индексирования.

Например, выражение поля «0.имя» вызовет 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).

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

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

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

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

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

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

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

«Спецификации формата» используются внутри полей замены, заключённых в строке формата, чтобы определить, как будут представлены отдельные значения (см. Синтаксис строки формата и Литералы форматированных строк). Их также можно передавать непосредственно встроенной функции 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().

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры форматирования

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

Строки-шаблоны

Строки-шаблоны предоставляют более простой способ подстановки строк, как описано в 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, оригинальный placeholder остаётся в результирующей строке без изменений. Кроме того, в отличие от 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 – Это литеральная строка, описывающая разделитель, вводящий placeholder. Значение по умолчанию — $. Обратите внимание, что это не должно быть регулярным выражением, так как реализация вызовет 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. Если вы это сделаете, значение должно быть объектом регулярного выражения с четырьмя именованными группами захвата. Группы захвата соответствуют правилам, указанным выше, вместе с правилом недействительного placeholder:

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

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

string.capwords(s, sep=None)

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