7.7. textwrap – Обёртывание и заполнение текста¶textwrap – Text wrapping and filling

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

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

textwrap.wrap(text[, width[, ...]])¶

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

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

См. метод TextWrapper.wrap() для дополнительных сведений о поведении wrap().

textwrap.fill(text[, width[, ...]])¶

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

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

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

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

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

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

textwrap.dedent(text)¶

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

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

Обратите внимание, что табуляция и пробелы считаются пробельными символами, но они не равнозначны: строки "  hello" и "\thello" считаются не имеющими общего начального пробела. (Это поведение новое в Python 2.5; более старые версии этого модуля некорректно разворачивали табуляцию перед поиском общего начального пробела.)

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

Например:

def test():
    # завершите первую строку символом \, чтобы избежать пустой строки
    s = '''\
    hello
      world
    '''
    print repr(s)          # выводит '    hello\n      world\n    '
    print repr(dedent(s))  # выводит 'hello\n  world\n'

class textwrap.TextWrapper(...)¶

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

wrapper = TextWrapper(initial_indent="* ")

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

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

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

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

width¶

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

expand_tabs¶

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

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, пробелы в начале и конце каждой строки (после переноса, но до добавления отступа) удаляются. Однако пробелы в начале абзаца не удаляются, если за ними следует непробельный символ. Если удаляемый пробел занимает всю строку, она удаляется целиком.

Новое в версии 2.6: В более ранних версиях пробелы всегда удалялись.

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. В предыдущих версиях поведение по умолчанию всегда разрешало разрыв слов с дефисом.

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

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

wrap(text)¶

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

fill(text)¶

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