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

Исходный код: 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, описанным ниже.

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

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

Новое в версии 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)¶: Заворачивает один абзац в текст (строку), так чтобы каждая строка была длиной не более width символов. Параметры обтекания берутся из атрибутов экземпляра TextWrapper. Возвращает список строк вывода, без конечных символов новой строки. Если завернутый вывод не содержит содержимого, возвращается пустой список.

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

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

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