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)

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

check_unused_args(used_args, args, kwargs)

Реализует проверку неиспользуемых аргументов при необходимости.

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>

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

См. также раздел Спецификатор формата.

Само имя_поля начинается с имени_аргумента, которое является либо числом, либо ключевым словом. Если это число, оно относится к позиционному аргументу, а если ключевое слово, оно относится к именованному аргументу. Если числовые имена аргументов в строке форматирования — 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. Пример библиотеки, построенной на строках шаблонов для локализации, см. в пакете flufl.i18n.

Строки шаблонов поддерживают подстановки, основанные на $, используя следующие правила:

• $$ является экранированием; оно заменяется на один $.
• $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.

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

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

string.capwords(s, sep=None)

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