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 и возвращает одну строку, содержащую обернутый абзац.