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

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

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

textwrap.wrap(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')¶

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

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

Дополнительные сведения о поведении метода TextWrapper.wrap() см. в методе wrap().

textwrap.fill(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')¶

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

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

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

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')¶

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

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

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

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

Обратите внимание, что табуляция и пробелы рассматриваются как пробельные символы, но они не равны: считается, что строки "  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)¶

Добавить префикс к началу выделенных строк в тексте.

Строки разделяются вызовом text.splitlines(True).

По умолчанию prefix добавляется ко всем строкам, которые состоят не только из пробельных символов (включая любые окончания строк).

Например:

>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'

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

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

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

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

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

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

Примечание

Если 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)¶

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

fill(text)¶

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