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[name]” или “label.title”. args и kwargs передаются в vformat().

get_value(key, args, kwargs)

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

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       ::=  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.

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

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

Методы этого класса возбудят исключение ValueError, если шаблон будет сопоставлен без соответствия одной из этих именованных групп.

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

string.capwords(s, sep=None)

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