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() для разбиения строки на литеральные тексты или поля замещения.

Значения в кортеже концептуально представляют отрезок литерального текста, за которым следует одно поле замещения. Если нет литерального текста (что может произойти, если две последовательно расположенные поля замещения), то literal_text будет пустой строкой. Если нет поля замещения, то значения field_name, format_spec и conversion будут None.

get_field(field_name, args, kwargs)

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

get_value(key, args, kwargs)

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

Параметр args устанавливается в список позиционных аргументов для vformat(), а параметр kwargs устанавливается в словарь именованных аргументов.

Для составных имен полей эти функции вызываются только для первого компонента имени поля; последующие компоненты обрабатываются с помощью обычных операций атрибутов и индексирования.

Например, выражение поля «0.имя» приведет к вызову get_value() с аргументом key равным 0. Атрибут name будет получен после get_value() с помощью вызова встроенной функции 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       ::=  <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. Пример библиотеки, построенной на строках шаблонов для i18n, см. в пакете 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 для разделения и соединения слов.