string – Общие операции со строками¶string – Common string operations

Константы строк¶String constants

Константы, определённые в этом модуле:

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-символы, которые считаются пробельными. Включает символы: пробел, табуляция, перевод строки, возврат каретки, прогон страницы и вертикальная табуляция.

Форматирование строк¶String Formatting

Встроенный строковый класс предоставляет возможность выполнять сложные подстановки переменных и форматирование значений с помощью метода format(), описанного в PEP 3101. Класс Formatter в модуле string позволяет создавать и настраивать собственное поведение форматирования строк, используя ту же реализацию, что и встроенный метод format().

class string.Formatter¶

Класс Formatter имеет следующие открытые методы:

format(format_string, *args, *kwargs)¶

format() – это основной метод API. Он принимает шаблон форматирования строку и произвольный набор позиционных и именованных аргументов. format() – это обёртка, которая вызывает vformat().

vformat(format_string, args, kwargs)¶

Эта функция выполняет фактическую работу по форматированию. Она вынесена как отдельная функция для случаев, когда нужно передать заранее определённый словарь аргументов, а не распаковывать и упаковывать словарь как отдельные аргументы с помощью синтаксиса *args и **kwds. vformat() выполняет разбиение шаблонной строки форматирования на символьные данные и поля замены. Она вызывает различные методы, описанные ниже.

Кроме того, класс Formatter определяет ряд методов, предназначенных для замены в подклассах:

parse(format_string)¶

Перебирает 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[name]" или "label.title". args и kwargs передаются в vformat(). Возвращаемое значение used_key имеет тот же смысл, что и параметр key для get_value().

get_value(key, args, kwargs)¶

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

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

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

Так, например, для поля с выражением ‘0.name’ будет вызвана 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()). Базовая версия понимает типы преобразования ‘r’ (repr) и ‘s’ (str).

Синтаксис строки формата¶Format String Syntax

Метод str.format() и класс Formatter используют одинаковый синтаксис форматных строк (хотя в случае Formatter подклассы могут определять собственный синтаксис форматных строк).

Строки форматирования содержат «поля замены», заключённые в фигурные скобки {}. Всё, что не находится в скобках, считается буквальным текстом и копируется в вывод без изменений. Если нужно включить символ скобки в буквальный текст, его можно экранировать удвоением: {{ и }}.

Грамматика поля замены выглядит следующим образом:

replacement_field ::=  "{" field_name ["!" conversion] [":" format_spec] "}"
field_name        ::=  (identifier | integer) ("." attribute_name | "[" element_index "]")*
attribute_name    ::=  identifier
element_index     ::=  integer
conversion        ::=  "r" | "s" | "a"
format_spec       ::=  <described in the next section>

В менее формальных терминах, поле замены начинается с field_name, который может быть либо числом (для позиционного аргумента), либо идентификатором (для именованных аргументов). За ним следует необязательное поле conversion, перед которым стоит восклицательный знак '!', и format_spec, перед которым стоит двоеточие ':'.

Сам field_name начинается либо с числа, либо с ключевого слова. Если это число, оно ссылается на позиционный аргумент; если ключевое слово – на именованный аргумент. За ним может следовать любое количество выражений индекса или атрибута. Выражение вида '.name' выбирает именованный атрибут с помощью getattr(), а выражение вида '[index]' выполняет доступ по индексу с помощью __getitem__().

Несколько простых примеров строк форматирования:

"First, thou shalt count to {0}" # Ссылается на первый позиционный аргумент
"My quest is {name}"             # Ссылается на именованный аргумент 'name'
"Weight in tons {0.weight}"      # Атрибут 'weight' первого позиционного аргумента
"Units destroyed: {players[0]}"  # Первый элемент именованного аргумента 'players'.

Поле conversion вызывает приведение типа перед форматированием. Обычно задачу форматирования значения выполняет метод __format__() самого этого значения. Однако в некоторых случаях желательно принудительно отформатировать тип как строку, переопределив его собственное определение форматирования. Преобразовав значение в строку перед вызовом __format__(), можно обойти обычную логику форматирования.

В настоящее время поддерживаются три флага преобразования: '!s', который вызывает str() для значения; '!r', вызывающий repr(); и '!a', вызывающий ascii().

Несколько примеров:

"Harold's a clever {0!s}"        # Сначала вызывает str() для аргумента
"Bring out the holy {name!r}"    # Сначала вызывает repr() для аргумента

Поле format_spec содержит спецификацию того, как должно быть представлено значение, включая такие детали, как ширина поля, выравнивание, заполнение, десятичная точность и так далее. Каждый тип значения может определять свой собственный «форматирующий мини-язык» или интерпретацию format_spec.

Большинство встроенных типов поддерживают общий мини-язык форматирования, который описан в следующем разделе.

Поле format_spec может также содержать вложенные поля замены. Эти вложенные поля замены могут содержать только имя поля; флаги преобразования и спецификации формата не допускаются. Поля замены внутри format_spec подставляются до того, как строка format_spec будет интерпретирована. Это позволяет динамически задавать форматирование значения.

Например, предположим, вы хотите создать поле замены, ширина которого определяется другой переменной:

"A man with two {0:{1}}".format("noses", 10)

Сначала будет вычислено внутреннее поле замены, в результате чего форматная строка станет такой:

"A man with two {0:10}"

Затем будет вычислено внешнее поле замены, и в итоге получится:

"noses     "

Подставляется в строку, в результате чего получается:

"A man with two noses     "

(Лишний пробел возникает из-за того, что указана ширина поля 10, и по умолчанию строки выравниваются по левому краю.)

format_spec ::=  [[fill]align][sign][#][0][width][.precision][type]
fill        ::=  <a character other than '}'>
align       ::=  "<" | ">" | "=" | "^"
sign        ::=  "+" | "-" | " "
width       ::=  integer
precision   ::=  integer
type        ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "x" | "X" | "%"

Шаблонные строки¶Template strings

Шаблоны предоставляют более простые подстановки строк, как описано в PEP 292. Вместо обычных подстановок на основе %, шаблоны поддерживают подстановки на основе $, используя следующие правила:

• $$ – это escape-последовательность; она заменяется на один символ $.
• $identifier обозначает заполнитель подстановки, соответствующий ключу отображения "identifier". По умолчанию, "identifier" должно быть корректным идентификатором Python. Первый символ, не являющийся идентификатором, после символа $ завершает этот спецификатор заполнителя.
• ${identifier} эквивалентно $identifier. Такая форма требуется, когда за заполнителем следуют символы, являющиеся корректными идентификаторами, но не входящие в состав заполнителя, как в "${noun}ification".

Любое другое появление $ в строке приведёт к возбуждению исключения ValueError.

Модуль string предоставляет класс Template, который реализует эти правила. Методы класса Template:

class string.Template(template)¶

Конструктор принимает единственный аргумент – строку шаблона.

substitute(mapping[, **kws])¶

Выполняет подстановку в шаблоне, возвращая новую строку. mapping – это любой объект, подобный словарю, с ключами, соответствующими заполнителям в шаблоне. В качестве альтернативы можно указать именованные аргументы, где имена аргументов являются заполнителями. Если указаны и mapping, и kws, и есть дубликаты, то заполнители из kws имеют приоритет.

safe_substitute(mapping[, **kws])¶

Похоже на substitute(), за исключением того, что если плейсхолдеры отсутствуют в mapping и kws, вместо возбуждения исключения KeyError, исходный плейсхолдер останется в результирующей строке нетронутым. Кроме того, в отличие от substitute(), любые другие вхождения $ будут просто возвращать $ вместо возбуждения ValueError.

Хотя другие исключения всё ещё могут возникать, этот метод называется «безопасным» (safe), потому что подстановки всегда стараются вернуть рабочую строку вместо возбуждения исключения. В другом смысле, safe_substitute() может быть чем угодно, но не безопасным, поскольку он молча игнорирует некорректные шаблоны, содержащие висячие разделители, несогласованные скобки или плейсхолдеры, не являющиеся валидными идентификаторами Python.

Экземпляры Template также предоставляют один открытый атрибут данных:

string.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 10
>>> 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-z][_a-z0-9]*.

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

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

Функции для строк¶String functions

Следующие функции доступны для работы со строковыми объектами. Они недоступны в качестве методов строк.

string.capwords(s)¶

Разделяет аргумент на слова с помощью split(), делает первую букву каждого слова заглавной с помощью capitalize() и объединяет слова, начинающиеся с заглавной буквы, с помощью join(). Обратите внимание, что эта функция заменяет последовательности пробельных символов одним пробелом и удаляет ведущие и завершающие пробелы.

string.maketrans(frm, to)¶

Возвращает таблицу перевода, подходящую для передачи в bytes.translate(), которая будет сопоставлять каждый символ из from с символом на той же позиции в to; from и to должны иметь одинаковую длину.