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

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

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

replace_whitespace: (по умолчанию: True) Если значение истинно, после раскрытия табуляций, но до переноса, метод wrap() заменит каждый пробельный символ одним пробелом. Заменяются следующие пробельные символы: табуляция, перевод строки, вертикальная табуляция, перевод страницы и возврат каретки ('\t\n\v\f\r').

Примечание

Если expand_tabs имеет значение false, а replace_whitespace — true, каждый символ табуляции будет заменён одним пробелом, что не равнозначно раскрытию табуляций.

Примечание

Если replace_whitespace имеет значение false, символы перевода строки могут оказаться посреди строки и привести к неожиданному выводу. Поэтому текст следует разделить на абзацы (с помощью str.splitlines() или аналогичного метода) и переносить их отдельно.

drop_whitespace: (по умолчанию: True) Если значение истинно, пробельные символы в начале и конце каждой строки удаляются (после переноса, но до добавления отступов). Однако пробельные символы в начале абзаца не удаляются, если за ними следуют непробельные символы. Если удаляемые пробельные символы занимают целую строку, вся строка удаляется.

initial_indent: (по умолчанию: '') Строка, добавляемая в начало первой строки перенесённого текста. Учитывается в длине первой строки. Пустая строка не получает отступа.

subsequent_indent: (по умолчанию: '') Строка, добавляемая в начало всех строк перенесённого текста, кроме первой. Учитывается в длине каждой строки, кроме первой.

fix_sentence_endings

(по умолчанию: False) Если значение истинно, TextWrapper пытается определять окончания предложений и следить за тем, чтобы предложения всегда разделялись ровно двумя пробелами. Обычно это желательно для текста, набранного моноширинным шрифтом. Однако алгоритм определения предложений несовершенен: он предполагает, что окончание предложения состоит из строчной буквы, за которой следует один из символов '.', '!' или '?', возможно, за которым следует один из символов '"' или "'", а затем пробел. Одна из проблем этого алгоритма заключается в том, что он не может отличить «Dr.» в

[...] Dr. Frankenstein's monster [...]

от «Spot.» в

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

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

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

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

break_on_hyphens: (по умолчанию: True) Если значение истинно, перенос будет по возможности выполняться по пробельным символам и сразу после дефисов в сложных словах, как принято в английском языке. Если значение ложно, потенциально подходящими местами для переноса будут считаться только пробельные символы; однако, чтобы слова действительно неразрывно сохранялись, необходимо установить 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–2025 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.13/library/textwrap.html