6.4. `textwrap` – Перенос и заполнение текста¶textwrap – Text wrapping and filling

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

The textwrap module provides two convenience functions, wrap() and fill(), as well as TextWrapper, the class that does all the work, and two utility functions, dedent() and indent(). If you’re just wrapping or filling one or two text strings, the convenience functions should be good enough; otherwise, you should use an instance of TextWrapper for efficiency.

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().

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

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

Две дополнительные вспомогательные функции, dedent() и indent(), предоставляются для удаления отступов из строк, содержащих нежелательные пробелы слева от текста, и для добавления произвольного префикса к выбранным строкам в блоке текста.

textwrap.dedent(text)¶

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

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

Обратите внимание, что табуляции и пробелы оба считаются пробельными символами, но они не равны: строки " hello" и "\thello" считаются не имеющими общего начального пробела.

Например:

def test():
    # завершите первую строку символом \, чтобы избежать пустой строки
    s = '''\
    hello
      world
    '''
    print(repr(s))          # выводит '    hello\n      world\n    '
    print(repr(dedent(s)))  # выводит '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

class textwrap.TextWrapper(**kwargs)¶

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

wrapper = TextWrapper(initial_indent="* ")

это то же самое, что

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

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

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

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

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

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

Новое в версии 3.3.

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

Примечание

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

Примечание

Если replace_whitespace ложно, символы новой строки могут оказаться в середине строки и привести к странному выводу. По этой причине текст следует разбивать на абзацы (с помощью 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, если требуются действительно неразрывные слова. Поведение по умолчанию в предыдущих версиях заключалось в том, чтобы всегда разрешать разрыв слов с дефисом.

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

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

fill(text)¶: Заворачивает один абзац в текст и возвращает одну строку, содержащую завернутый абзац.

6.4. textwrap – Перенос и заполнение текста¶textwrap – Text wrapping and filling

6.4. `textwrap` – Перенос и заполнение текста¶textwrap – Text wrapping and filling