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'

Изменено в версии 3.14: Теперь функция dedent() правильно нормализует пустые строки, содержащие только пробельные символы. Ранее реализация нормализовала только пустые строки, содержащие табуляции и пробелы.

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 имеет значение false, а replace_whitespace — true, каждый символ табуляции будет заменён одним пробелом, что не равнозначно преобразованию табуляции.

Примечание

Если replace_whitespace имеет значение false, символы перевода строки могут оказаться посреди строки и привести к неожиданному результату. Поэтому текст следует разбить на абзацы (например, с помощью str.splitlines() или аналогичного средства) и переносить каждый абзац отдельно.

drop_whitespace

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

initial_indent

(значение по умолчанию: '') Строка, добавляемая в начало первой строки результата переноса. Учитывается в длине первой строки. Пустая строка не получает отступа.

subsequent_indent

(значение по умолчанию: '') Строка, добавляемая в начало всех строк результата переноса, кроме первой. Учитывается в длине каждой строки, кроме первой.

fix_sentence_endings

(значение по умолчанию: False) Если значение истинно, TextWrapper пытается определить окончания предложений и обеспечить между предложениями ровно два пробела. Обычно это желательно для текста, набранного моноширинным шрифтом. Однако алгоритм определения предложений несовершенен: он предполагает, что окончание предложения состоит из строчной буквы, за которой следует один из символов '.', '!' или '?', возможно, за которым следует один из символов '"' или "'", а затем пробел. Один из недостатков этого алгоритма в том, что он не может отличить «Dr.» в

[...] Dr. Frankenstein's monster [...]

от «Spot.» в

[...] See Spot. See Spot run [...]

По умолчанию fix_sentence_endings имеет значение false.

Поскольку алгоритм определения предложений использует string.lowercase для определения «строчной буквы» и опирается на принятую в английском языке условность ставить два пробела после точки для разделения предложений в одной строке, он подходит только для текстов на английском языке.

break_long_words

(значение по умолчанию: True) Если значение истинно, слова длиннее width будут разбиваться, чтобы длина строк не превышала width. Если значение false, длинные слова не будут разбиваться, и некоторые строки могут быть длиннее width. (Длинные слова будут помещаться в отдельную строку, чтобы свести к минимуму превышение width.)

break_on_hyphens

(значение по умолчанию: 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)

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