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 даже к пустым и содержащим только пробелы строкам:

>>> 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.10/library/textwrap.html