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 не повлияет на результат.

Введено в версии 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

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

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

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

END_OF_DOCUMENT_MARKER

class textwrap.TextWrapper(**kwargs)

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

wrapper = TextWrapper(initial_indent="* ")

то же самое, что и

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

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

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

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

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

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

Новое в версии 3.3.

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

Примечание

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

Примечание

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

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

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

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

fix_sentence_endings

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

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

и “Spot.” в

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

fix_sentence_endings по умолчанию ложно.

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

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

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

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

Новое в версии 3.4.

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

Новое в версии 3.4.

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

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

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