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

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

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. Frankenstein's monster [...]

и «Скот.» в

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

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