string — Операции с текстовыми строками

Строковые константы

В этом модуле определены следующие константы:

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

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

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

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

Метод 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:       format-spec:format_spec

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

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

Само поле field_name начинается с arg_name, представляющего собой число или ключевое слово. Если это число, оно указывает на позиционный аргумент; если ключевое слово — на именованный аргумент. arg_name считается числом, если вызов str.isdecimal() для этой строки возвращает истину. Если числовые arg_names в строке форматирования идут последовательно: 0, 1, 2, …, их можно опустить все (но не только некоторые), и числа 0, 1, 2, … будут автоматически подставлены в этом порядке. Поскольку arg_name не ограничивается кавычками, в строке форматирования нельзя указать произвольные ключи словаря (например, строки '10' или ':-]'). За arg_name может следовать любое количество выражений индексации или доступа к атрибутам. Выражение вида '.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'.

Поле conversion приводит тип значения перед форматированием. Обычно форматированием значения занимается метод __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_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+ 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'

>>> "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}'.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'

>>> # 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'
>>> '{:_}'.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

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

Шаблонные строки обеспечивают более простую подстановку строк, описанную в PEP 292. Основной вариант использования шаблонных строк — интернационализация (i18n), поскольку в этом контексте более простой синтаксис и функциональность облегчают перевод по сравнению с другими встроенными средствами форматирования строк в Python. Пример библиотеки для интернационализации на основе шаблонных строк — пакет 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.11.

get_identifiers()

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

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

Экземпляры 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 — эта группа соответствует escape-последовательности, например $$ в шаблоне по умолчанию.
• named — эта группа соответствует имени заполнителя без фигурных скобок; группа захвата не должна включать разделитель.
• braced — эта группа соответствует имени заполнителя в фигурных скобках; группа захвата не должна включать ни разделитель, ни фигурные скобки.
• invalid — эта группа соответствует любому другому шаблону разделителя (обычно одному разделителю); она должна находиться в конце регулярного выражения.

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

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

string.capwords(s, sep=None)

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