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

Исходный код: 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():
    # завершите первую строку символом \, чтобы избежать пустой строки
    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

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

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

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

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

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

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

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

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

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

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