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

Сверните и обрежьте заданный текст, чтобы он соответствовал заданной ширине.

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

>>> 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)¶

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

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

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

Например:

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

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

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

и «Пятно». в

[...] 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, а в конце выходных данных появится заполнитель.

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

placeholder¶

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

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

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

wrap(text)¶

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

fill(text)¶

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