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_name в форматной строке идут последовательно: 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][grouping]["." precision][type]
options     ::= [[fill]align][sign]["z"]["#"]["0"]
fill        ::= <any character>
align       ::= "<" | ">" | "=" | "^"
sign        ::= "+" | "-" | " "
width       ::= digit+
grouping    ::= "," | "_"
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'
>>> '{:_}'.format(1234567890)
'1_234_567_890'
>>> '{:_b}'.format(1234567890)
'100_1001_1001_0110_0000_0010_1101_0010'
>>> '{:_x}'.format(1234567890)
'4996_02d2'

>>> 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.