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

Исходный код: Lib/textwrap.py

---

Модуль textwrap предоставляет некоторые удобные функции, а также класс TextWrapper, который выполняет всю работу. Если вы просто упаковываете или заполняете один или два текстовых строки, функции удобства должны быть достаточно хорошими; в противном случае для эффективности следует использовать сущность TextWrapper.

textwrap.wrap(text, width=70, **kwargs)

Помещает отдельный абзац в text (строка), поэтому длина каждой строки не превышает width символов. Возвращает список выходных строк без символов завершения строк.

Дополнительные ключевые аргументы соответствуют атрибутам сущности TextWrapper, документированного ниже. По умолчанию width к 70.

Дополнительные сведения о поведении TextWrapper.wrap() см. в методе wrap().

textwrap.fill(text, width=70, **kwargs)

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

"\n".join(wrap(text, ...))

В частности, fill() принимает точно такие же ключевые аргументы, как и wrap().

textwrap.shorten(text, width, **kwargs)

Сворачивание и усечение данного 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():
    # завершить первую строку \, чтобы избежать пустой строки!
    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, '+ ', lambd 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() заменяет каждый символ пробела единым пробелом. Заменяются следующие символы пробела: tab, newline, vertical tab, formfeed и возвращение каретки ('\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 [...]

и «Пятно.» в:

[...] See Spot. See Spot run [...]

По умолчанию fix_sentence_endings имеет значение false.

Поскольку алгоритм обнаружения предложений опирается на string.lowercase для определения «строчной буквы», и соглашение об использовании двух пробелов через период для разделения предложений в одной строке, оно специфично для англоязычных текстов.

break_long_words

(по умолчанию: True) если true, то слова длиннее width будут разбиты, чтобы гарантировать, что ни одна строка не длиннее width. Если это ложь, длинные слова не будут разбиты, а некоторые строки могут быть длиннее width. (Длинные слова будут поставлены на строку сами по себе, чтобы минимизировать сумму, на которую width превышен.)

break_on_hyphens

(по умолчанию: True) если true, обертка будет выполняться предпочтительно в белых пространствах и сразу после дефисов составными словами, как это принято в английском языке. Если значение равно false, в качестве потенциально хороших мест для разрывов строк будут рассматриваться только пробелы, но если вам нужны действительно незащищенные слова, необходимо установить значение false для break_long_words. Поведение по умолчанию в предыдущих версиях должно было всегда разрешать разрыв слов с переносами.

max_lines

(по умолчанию: None) если не None, то вывод будет содержать не более max_lines строк, причем placeholder появится в конце вывода.

Добавлено в версии 3.4.

placeholder

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

Добавлено в версии 3.4.

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

wrap(text)

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

fill(text)

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