textwrap — Упаковка и форматирование текста

Новая версия с 2.3.

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

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

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

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

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

Дополнительные сведения о работе функции wrap() см. в методе TextWrapper.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():
    # 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'

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 ложно, а replace_whitespace истинно, каждый символ табуляции будет заменён одним пробелом, что не эквивалентно расширению табуляции.

Примечание

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

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

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

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

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

fix_sentence_endings

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

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

от «Спот.» в

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

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

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

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

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

В версии 2.6.

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

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

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