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

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

• $$ — это 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.

Экземпляры 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, что означает использование того же шаблона (внутри и вне фигурных скобок).

  Добавлен в версии 3.7.

• flags — флаги регулярных выражений, которые будут применяться при компиляции регулярного выражения для распознавания подстановок. Значение по умолчанию re.IGNORECASE. Обратите внимание, что re.VERBOSE всегда добавляется к флагам, поэтому пользовательские idpattern должны следовать соглашениям для подробных регулярных выражений.

  Добавлен в версии 3.2.

В качестве альтернативы вы можете указать всё регулярное выражение, переопределяя свойство класса pattern. Если вы это делаете, значение должно быть объектом регулярного выражения с четырьмя именованными группами захвата. Группы захвата соответствуют правилам, приведенным выше, а также правилу недопустимого заполнителя:

• escaped — эта группа соответствует последовательности escape, например, $$, в шаблоне по умолчанию.
• named — эта группа соответствует имени заполнителя без фигурных скобок; она не должна включать разделитель в группе захвата.
• braced — эта группа соответствует имени заполнителя в фигурных скобках; она не должна включать ни разделитель, ни фигурные скобки в группе захвата.
• invalid — эта группа соответствует любому другому шаблону разделителей (обычно одиночному разделителю), и она должна стоять последней в регулярном выражении.

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

string.capwords(s, sep=None)

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