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) Если True, то все символы табуляции в тексте text будут преобразованы в пробелы с помощью метода expandtabs() объекта text.

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

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

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

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

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

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

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

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

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

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

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