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() (см. выше), в объект для форматирования. Возвращает кортеж (obj, used_key).

get_value(key, args, kwargs)

Получает значение заданного поля.

check_unused_args(used_args, args, kwargs)

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

format_field(value, format_spec)

Просто вызывает встроенную глобальную функцию format().

convert_field(value, conversion)

Преобразует значение (возвращаемое get_field()) с учётом типа преобразования (как в кортеже, возвращаемом методом parse()).

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

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

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

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

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