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'

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

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

© 2001–2023 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.11/library/textwrap.html