`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, которые описаны ниже.

Дополнительные сведения о том, как ведет себя 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=' [...]')¶

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

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

>>> 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 не будет иметь никакого эффекта.

Added in version 3.4.

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

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

Например:

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

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

>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world

Added in version 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, то все символы табуляции в тексте будут расширены до нуля или более пробелов, в зависимости от текущего столбца и заданного размера табуляции.

Added in version 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.

Added in version 3.4.

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

Added in version 3.4.

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

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

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

`textwrap` — Обертывание и заполнение текста¶

Предыдущий раздел

Следующий раздел

textwrap — Обертывание и заполнение текста¶

`textwrap` — Обертывание и заполнение текста¶