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=' [...]')

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

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

Дополнительные сведения о поведении wrap() см. в методе TextWrapper.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=' [...]')

Сжимает и укорачивает заданный 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.

class textwrap.TextWrapper(**kwargs)

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

wrapper = TextWrapper(initial_indent="* ")

эквивалентно

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

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

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

width

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

expand_tabs

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

tabsize

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

Введено в версии 3.3.

replace_whitespace

(по умолчанию: True) Если истинно, после расширения табуляции, но перед обёртыванием, метод wrap() заменит каждый символ пробела одним пробелом. Символы пробелов, которые заменяются, указаны ниже: табуляция, новая строка, вертикальная табуляция, разделитель страницы и возврат каретки ('\t\n\v\f\r').

Примечание

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

Примечание

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

drop_whitespace

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

initial_indent

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

subsequent_indent

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

fix_sentence_endings

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

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

от «Свот.» в

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

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

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

break_long_words

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

break_on_hyphens

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

max_lines

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

Введено в версии 3.4.

placeholder

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

Введено в версии 3.4.

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

wrap(text)

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

fill(text)

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