`textwrap` — Обёртывание и заполнение текста

Модуль 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():
    # Завершить первую строку символом \ чтобы избежать пустой строки!
    s = '''\
    hello
      world
    '''
    print(repr(s))          # распечатает '    hello\n      world\n    '
    print(repr(dedent(s)))  # распечатает '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 даже к пустым строкам и строкам, состоящим только из пробелов:

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

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

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

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

class textwrap.TextWrapper(**kwargs)

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

wrapper = TextWrapper(initial_indent="* ")

такой же, как:

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

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

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

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

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

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

Добавлено в версии 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 строк, причем placeholder появится в конце вывода.

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

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

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

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

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

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

textwrap — Обёртывание и заполнение текста

`textwrap` — Обёртывание и заполнение текста