textwrap — Обёртка и форматирование текста

Исходный код: Lib/textwrap.py

Модуль textwrap предоставляет удобные функции, а также класс TextWrapper, который выполняет всю работу. Если вам нужно обернуть или отформатировать одну или две строки текста, то функций достаточно; в противном случае, для повышения эффективности вы должны использовать экземпляр класса TextWrapper.

textwrap.wrap(text, width=70, **kwargs)

Обрезает единственный абзац в text (строка), чтобы каждая строка содержала не более width символов. Возвращает список выходных строк без конечных символов новой строки.

Необязательные ключевые аргументы соответствуют атрибутам экземпляра TextWrapper, документация которых приведена ниже. Значение width по умолчанию равно 70.

Дополнительные сведения о том, как работает wrap(), см. в методе TextWrapper.wrap().

textwrap.fill(text, width=70, **kwargs)

Обрезает единственный абзац в text и возвращает одну строку, содержащую отформатированный абзац. fill() — это сокращённая форма

"\n".join(wrap(text, ...))

В частности, fill() принимает те же ключевые аргументы, что и wrap().

textwrap.shorten(text, width, **kwargs)

Сжимает и укорачивает заданный text, чтобы он уместился в заданную width.

Сначала пробелы в text сжимаются (все пробелы заменяются одним пробелом). Если результат умещается в width, он возвращается. В противном случае из конца удаляются достаточно слов, чтобы оставшиеся слова плюс placeholder уместились в width:

>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'

Необязательные ключевые аргументы соответствуют атрибутам экземпляра TextWrapper, документация которых приведена ниже. Обратите внимание, что пробелы сжимаются перед передачей текста функции TextWrapper fill(), поэтому изменение значения tabsize, expand_tabs, drop_whitespace и replace_whitespace не повлияет.

New in version 3.4.

textwrap.dedent(text)

Удаляет любые общие начальные пробелы из каждой строки в text.

Это может использоваться для выравнивания строк в строках с тройными кавычками по левому краю экрана, сохраняя при этом их отступы в исходном коде.

Обратите внимание, что табуляции и пробелы обрабатываются как пробелы, но они не равны: строки " hello" и "\thello" считаются не имеющими общих начальных пробелов.

Например:

def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'

textwrap.indent(text, prefix, predicate=None)

Добавляет prefix к началу выбранных строк в text.

Строки разделяются вызовом text.splitlines(True).

По умолчанию, prefix добавляется ко всем строкам, которые не состоят только из пробелов (включая любые символы конца строки).

Например:

>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'

Необязательный аргумент predicate может использоваться для управления строками, к которым добавляется prefix. Например, легко добавить prefix даже к пустым и содержащим только пробелы строкам:

>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world

New in version 3.3.

wrap(), fill() и shorten() работают путём создания экземпляра TextWrapper и вызова одного метода на нём. Этот экземпляр не переиспользуется, поэтому для приложений, обрабатывающих множество строк текста с помощью wrap() и/или fill(), может быть эффективнее создать собственный объект TextWrapper.

Текст предпочтительно обрезается по пробелам и сразу после тире в словах с дефисом; только тогда длинные слова будут разбиваться при необходимости, если TextWrapper.break_long_words не установлено в false.

class textwrap.TextWrapper(**kwargs)

Конструктор TextWrapper принимает ряд необязательных ключевых аргументов. Каждый ключевой аргумент соответствует атрибуту экземпляра, поэтому, например,

wrapper = TextWrapper(initial_indent="* ")

эквивалентно

wrapper = TextWrapper()
wrapper.initial_indent = "* "

Вы можете многократно использовать один и тот же объект TextWrapper, и вы можете изменить любые его параметры, выполнив прямое присваивание атрибутам экземпляра между использованиями.

Атрибуты экземпляра TextWrapper (и ключевые аргументы конструктора) следующие:

width: (по умолчанию: 70) Максимальная длина обернутых строк. До тех пор, пока в входном тексте нет отдельных слов, длина которых больше, чем width, TextWrapper гарантирует, что длина ни одной выходной строки не будет превышать width символов.

expand_tabs: (по умолчанию: True) Если True, то все символы табуляции в text будут преобразованы в пробелы с помощью метода expandtabs() объекта text.

tabsize: (по умолчанию: 8) Если expand_tabs равно True, то все символы табуляции в text будут преобразованы в нуль или более пробелов в зависимости от текущего столбца и заданного размера табуляции.

Введено в версии 3.3.

replace_whitespace: (по умолчанию: True) Если True, после расширения табуляции, но перед обёртыванием, метод wrap() заменит каждый символ пробела одним пробелом. Символами пробела, которые заменяются, являются: табуляция, перевод строки, вертикальная табуляция, разделитель страницы и возврат каретки ('\t\n\v\f\r').

Примечание

Если expand_tabs равно False, а replace_whitespace равно True, каждый символ табуляции будет заменён одним пробелом, что не эквивалентно расширению табуляции.

Примечание

Если replace_whitespace равно False, переводы строк могут появиться посередине строки и вызвать странный вывод. По этой причине текст следует разбить на абзацы (используя str.splitlines() или аналогично), которые обертываются по отдельности.

drop_whitespace: (по умолчанию: True) Если True, пробелы в начале и конце каждой строки (после обёртывания, но до отступа) удаляются. Однако пробелы в начале абзаца не удаляются, если за ними следуют символы, отличные от пробелов.

initial_indent: (по умолчанию: '') Строка, которая будет добавлена перед первой строкой обернутого вывода. Учитывается в длине первой строки. Пустая строка не создаёт отступ.

subsequent_indent: (по умолчанию: '') Строка, которая будет добавлена перед всеми строками обернутого вывода, кроме первой. Учитывается в длине каждой строки, кроме первой.

fix_sentence_endings

(по умолчанию: False) Если True, TextWrapper пытается определить окончания предложений и гарантирует, что предложения всегда разделяются ровно двумя пробелами. Это обычно желательно для текста в моноширинном шрифте. Однако алгоритм определения предложений несовершенен: он предполагает, что окончание предложения состоит из строчной буквы, за которой следует один из символов '.', '!', или '?', возможно, за которым следует один из символов '"' или "'", за которым следует пробел. Одна из проблем с этим алгоритмом заключается в том, что он не может различить «Dr.» в

[...] Dr. Frankenstein's monster [...]

и «Spot.» в

[...] See Spot. See Spot run [...]

fix_sentence_endings по умолчанию равно False.

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

break_long_words: (по умолчанию: True) Если True, слова, длина которых больше, чем width, будут разбиты, чтобы гарантировать, что ни одна строка не будет длиннее, чем width. Если False, длинные слова не будут разбиваться, и некоторые строки могут быть длиннее width. (Длинные слова будут помещаться на отдельную строку, чтобы минимизировать превышение значения width).

break_on_hyphens: (по умолчанию: True) Если True, обёртывание будет происходить предпочтительно на пробелах и сразу после дефисов в сложных словах, как это принято в английском языке. Если False, в качестве потенциальных мест разрыва строк будут рассматриваться только пробелы, но вам необходимо установить break_long_words в False, если вы хотите полностью неразрывные слова. Поведение по умолчанию в предыдущих версиях всегда позволяло разрыв слов с дефисами.

max_lines: (по умолчанию: None) Если не None, то вывод будет содержать не более max_lines строк, при этом placeholder будет появляться в конце вывода.

Введено в версии 3.4.

placeholder: (по умолчанию: ' [...]') Строка, которая будет появляться в конце вывода текста, если он был усечён.

Введено в версии 3.4.

TextWrapper также предоставляет некоторые публичные методы, аналогичные функциям удобства на уровне модуля:

wrap(text): Обёртывает единственный абзац в text (строка) так, чтобы каждая строка имела длину не более width символов. Все параметры обёртывания взяты из атрибутов экземпляра объекта TextWrapper. Возвращает список выходных строк без конечных переводов строк. Если обернутый вывод не содержит содержимого, возвращаемый список пуст.

fill(text): Обёртывает единственный абзац в text и возвращает одну строку, содержащую обернутый абзац.