7.5. textwrap – Перенос и заполнение текста¶textwrap – Text wrapping and filling

Модуль textwrap предоставляет две вспомогательные функции – wrap() и fill(), а также TextWrapper – класс, который делает всю работу, и служебную функцию dedent(). Если нужно перенести или заполнить одну-две текстовые строки, достаточно вспомогательных функций; в противном случае для эффективности лучше использовать экземпляр TextWrapper.

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

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

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

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

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

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

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

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

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

Дополнительная служебная функция dedent() предназначена для удаления отступов из строк, содержащих нежелательные пробелы слева от текста.

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'

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.

replace_whitespace¶

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

Примечание

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

Примечание

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

drop_whitespace¶

(по умолчанию: 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, если требуются действительно неразрывные слова. Поведение по умолчанию в предыдущих версиях заключалось в том, чтобы всегда разрешать разрыв слов с дефисом.

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

wrap(text)¶

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

fill(text)¶

Заворачивает один абзац в текст и возвращает одну строку, содержащую завернутый абзац.