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–2024 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.12/library/textwrap.html