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.

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. После возврата из get_value() атрибут name будет найден посредством вызова встроенной функции 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() для строки вернул бы true. Если числовые 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     ::= [[fill]align][sign]["z"]["#"]["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" | "%"

>>> '{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'

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