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, все символы табуляции в тексте будут преобразованы в пробелы с помощью метода expandtabs() объекта текст.

tabsize: (по умолчанию: 8) Если expand_tabs равно True, все символы табуляции в тексте будут преобразованы в ноль или более пробелов, в зависимости от текущего столбца и заданного размера табуляции.

Добавлен в версии 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. Frankenstein's monster [...]

и «Скот.» в

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

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

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