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

get_field(field_name, args, kwargs)

Преобразует field_name, полученный из parse() (см. выше), в объект для форматирования. Возвращает кортеж (объект, используемый_ключ). Стандартная версия работает со строками в формате, определённом в PEP 3101, таких как «0[имя]» или «метка.заголовок». args и kwargs передаются в vformat().

get_value(key, args, kwargs)

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

check_unused_args(used_args, args, kwargs)

Реализация проверки неиспользованных аргументов, если нужно. Аргументы этой функции — множество всех ключей аргументов, которые фактически упоминались в строке формата (целые числа для позиционных аргументов и строки для именованных аргументов), а также ссылки на args и kwargs, которые были переданы в vformat. Множество неиспользованных аргументов может быть рассчитано из этих параметров.

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

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

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

Само имя_поля начинается с имени_аргумента, которое является либо числом, либо ключевым словом. Если это число, оно относится к позиционному аргументу, а если ключевое слово, то к именованному аргументу. Имя_аргумента обрабатывается как число, если вызов str.isdecimal() над строкой вернёт значение true. Если числовые имена аргументов в строке форматирования расположены последовательно (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

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

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

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

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

Строки шаблонов

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

Вот пример использования шаблона:

>>> 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 используется для разделения и соединения слов.