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 даже к пустым и содержащим только пробелы строкам:

>>> 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 имеет значение 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): Выравнивает единственный абзац в тексте и возвращает одну строку, содержащую выровненный абзац.