textwrap.md

1> **Источник:** https://python-all.ru/3/library/textwrap.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `textwrap` – Перенос и заполнение текста89**Исходный код:** [Lib/textwrap.py](https://python-all.ru/src/3.14/Lib/textwrap.py)1011---1213Модуль `textwrap` предоставляет несколько удобных функций, а также класс [`TextWrapper`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper), который выполняет всю основную работу. Если нужно всего лишь перенести или дополнить одну-две текстовые строки, удобных функций должно быть достаточно; в противном случае для эффективности следует использовать экземпляр `TextWrapper`.1415#### `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=' [...]')`1617Переносит единственный абзац в *text* (строку) так, что каждая строка не длиннее *width* символов. Возвращает список выходных строк, без завершающих символов новой строки.1819Необязательные именованные аргументы соответствуют атрибутам экземпляра [`TextWrapper`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper), описанным ниже.2021См. метод [`TextWrapper.wrap()`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.wrap) для дополнительных сведений о поведении `wrap()`.2223#### `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=' [...]')`2425Переносит единственный абзац в *text* и возвращает одну строку, содержащую перенесённый абзац. `fill()` – это сокращённая форма записи для2627```python28"\n".join(wrap(text, ...))29```3031В частности, `fill()` принимает те же именованные аргументы, что и [`wrap()`](https://python-all.ru/3/library/textwrap.html#textwrap.wrap).3233#### `textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')`3435Сжимает и обрезает заданный *text*, чтобы он поместился в заданную *width*.3637Сначала все пробельные символы в *text* сжимаются (все пробелы заменяются одиночными пробелами). Если результат помещается в *width*, он возвращается. В противном случае из конца отбрасывается достаточно слов, чтобы оставшиеся слова вместе с *placeholder* поместились в *width*:3839```python40>>> textwrap.shorten("Hello  world!", width=12)41'Hello world!'42>>> textwrap.shorten("Hello  world!", width=11)43'Hello [...]'44>>> textwrap.shorten("Hello world", width=10, placeholder="...")45'Hello...'46```4748Необязательные именованные аргументы соответствуют атрибутам экземпляра [`TextWrapper`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper), описанным ниже. Обратите внимание: пробельные символы сжимаются до передачи текста в функцию `TextWrapper` [`fill()`](https://python-all.ru/3/library/textwrap.html#textwrap.fill), поэтому изменение значений [`tabsize`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.tabsize), [`expand_tabs`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.expand_tabs), [`drop_whitespace`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.drop_whitespace) и [`replace_whitespace`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.replace_whitespace) не даст эффекта.4950Добавлено в версии 3.4.5152#### `textwrap.dedent(text)`5354Удаляет общие начальные пробельные символы из каждой строки в *text*.5556Это можно использовать, чтобы выровнять строки с тройными кавычками по левому краю отображения, при этом в исходном коде они остаются с отступами.5758Обратите внимание: табуляции и пробелы считаются пробельными символами, но они не равны: строки `" hello"` и `"\thello"` считаются не имеющими общих начальных пробельных символов.5960Строки, содержащие только пробельные символы, игнорируются во входном тексте и нормализуются до одного символа новой строки в выходном.6162Например:6364```python65def test():66    # завершите первую строку символом \, чтобы избежать пустой строки67    s = '''\68    hello69      world70    '''71    print(repr(s))          # выводит '    hello\n      world\n    '72    print(repr(dedent(s)))  # выводит 'hello\n  world\n'73```7475Изменено в версии 3.14: Функция `dedent()` теперь корректно нормализует пустые строки, содержащие только пробельные символы. Ранее реализация нормализовала только пустые строки, содержащие табуляции и пробелы.7677#### `textwrap.indent(text, prefix, predicate=None)`7879Добавляет *prefix* в начало выбранных строк в *text*.8081Строки разделяются вызовом `text.splitlines(True)`.8283По умолчанию *prefix* добавляется ко всем строкам, не состоящим только из пробельных символов (включая концы строк).8485Например:8687```python88>>> s = 'hello\n\n \nworld'89>>> indent(s, '  ')90'  hello\n\n \n  world'91```9293Необязательный аргумент *predicate* можно использовать для управления тем, какие строки получают отступ. Например, легко добавить *prefix* даже к пустым строкам и строкам, состоящим только из пробелов:9495```python96>>> print(indent(s, '+ ', lambda line: True))97+ hello98+99+100+ world101```102103Добавлено в версии 3.3.104105[`wrap()`](https://python-all.ru/3/library/textwrap.html#textwrap.wrap), [`fill()`](https://python-all.ru/3/library/textwrap.html#textwrap.fill) и [`shorten()`](https://python-all.ru/3/library/textwrap.html#textwrap.shorten) работают путём создания экземпляра [`TextWrapper`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper) и вызова единственного метода на нём. Этот экземпляр не используется повторно, поэтому для приложений, обрабатывающих много текстовых строк с помощью `wrap()` и/или `fill()`, может быть эффективнее создать собственный объект `TextWrapper`.106107Текст предпочтительно переносится по пробелам и сразу после дефисов в словах с дефисом; только после этого при необходимости разбиваются длинные слова, если только [`TextWrapper.break_long_words`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.break_long_words) не установлен в значение false.108109#### `class textwrap.TextWrapper(**kwargs)`110111Конструктор `TextWrapper` принимает ряд необязательных именованных аргументов. Каждый именованный аргумент соответствует атрибуту экземпляра, так, например112113```python114wrapper = TextWrapper(initial_indent="* ")115```116117это то же самое, что118119```python120wrapper = TextWrapper()121wrapper.initial_indent = "* "122```123124Один и тот же объект `TextWrapper` можно использовать многократно, причём можно изменять любые его параметры прямым присваиванием атрибутам экземпляра между использованиями.125126Атрибуты экземпляра `TextWrapper` (и ключевые аргументы конструктора) следующие:127128#### `width`129130(по умолчанию: `70`) Максимальная длина перенесённых строк. Если во входном тексте нет отдельных слов длиннее [`width`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.width), `TextWrapper` гарантирует, что ни одна строка вывода не будет длиннее `width` символов.131132#### `expand_tabs`133134(по умолчанию: `True`) Если true, все символы табуляции в *text* будут заменены на пробелы с помощью метода [`expandtabs()`](https://python-all.ru/3/library/stdtypes.html#str.expandtabs) *text*.135136#### `tabsize`137138(по умолчанию: `8`) Если [`expand_tabs`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.expand_tabs) равно true, все символы табуляции в *text* будут заменены на ноль или больше пробелов в зависимости от текущей позиции столбца и заданного размера табуляции.139140Добавлено в версии 3.3.141142#### `replace_whitespace`143144(по умолчанию: `True`) Если true, после замены табуляции, но до переноса строк, метод [`wrap()`](https://python-all.ru/3/library/textwrap.html#textwrap.wrap) заменит каждый пробельный символ на один пробел. Заменяемыми пробельными символами являются: табуляция, новая строка, вертикальная табуляция, перевод страницы и возврат каретки (`'\t\n\v\f\r'`).145146> **Примечание**147>148> Если [`expand_tabs`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.expand_tabs) равно false, а [`replace_whitespace`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.replace_whitespace) – true, каждый символ табуляции будет заменён одним пробелом, что *не* то же самое, что и замена табуляции.149150> **Примечание**151>152> Если [`replace_whitespace`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.replace_whitespace) равно false, символы новой строки могут появляться в середине строки и приводить к странному выводу. По этой причине текст следует разбивать на абзацы (с помощью [`str.splitlines()`](https://python-all.ru/3/library/stdtypes.html#str.splitlines) или аналогичных средств), которые переносятся отдельно.153154#### `drop_whitespace`155156(по умолчанию: `True`) Если true, пробелы в начале и конце каждой строки (после переноса, но до добавления отступа) удаляются. Однако пробелы в начале абзаца не удаляются, если за ними следует непробельный символ. Если удаляемый пробел занимает всю строку, она удаляется целиком.157158#### `initial_indent`159160(по умолчанию: `''`) Строка, которая будет добавлена к первой строке перенесённого вывода. Учитывается в длине первой строки. Пустая строка не добавляет отступ.161162#### `subsequent_indent`163164(по умолчанию: `''`) Строка, которая будет добавлена ко всем строкам перенесённого вывода, кроме первой. Учитывается в длине каждой строки, кроме первой.165166#### `fix_sentence_endings`167168(по умолчанию: `False`) Если true, `TextWrapper` пытается обнаружить концы предложений и гарантирует, что предложения всегда разделяются ровно двумя пробелами. Обычно это желательно для текста в моноширинном шрифте. Однако алгоритм обнаружения концов предложений несовершенен: он предполагает, что конец предложения состоит из строчной буквы, за которой следует один из `'.'`, `'!'` или `'?'`, возможно, за которым следует `'"'` или `"'"`, а затем пробел. Одна из проблем этого алгоритма в том, что он не может различить «Dr.» в169170```python171[...] Dr. Frankenstein's monster [...]172```173174и «Spot.» в175176```python177[...] See Spot. See Spot run [...]178```179180[`fix_sentence_endings`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.fix_sentence_endings) по умолчанию равно false.181182Поскольку алгоритм обнаружения концов предложений использует `string.lowercase` для определения «строчной буквы» и основан на соглашении об использовании двух пробелов после точки для разделения предложений на одной строке, он применим только к текстам на английском языке.183184#### `break_long_words`185186(по умолчанию: `True`) Если true, слова длиннее [`width`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.width) будут разбиты, чтобы ни одна строка не была длиннее `width`. Если false, длинные слова не разбиваются, и некоторые строки могут быть длиннее `width`. (Длинные слова будут размещены на отдельной строке, чтобы минимизировать превышение `width`.)187188#### `break_on_hyphens`189190(по умолчанию: `True`) Если true, перенос будет выполняться предпочтительно по пробелам и сразу после дефисов в составных словах, как принято в английском. Если false, только пробелы будут считаться потенциально хорошими местами для разрыва строк, но для полного запрета разрыва слов нужно установить [`break_long_words`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.break_long_words) в false. В предыдущих версиях поведение по умолчанию всегда разрешало разрыв слов с дефисом.191192#### `max_lines`193194(по умолчанию: `None`) Если не `None`, то вывод будет содержать не более *max\_lines* строк, причём в конце вывода будет отображаться *placeholder*.195196Добавлено в версии 3.4.197198#### `placeholder`199200(по умолчанию: `' [...]'`) Строка, которая появится в конце вывода, если текст был сокращён.201202Добавлено в версии 3.4.203204`TextWrapper` также предоставляет несколько открытых методов, аналогичных вспомогательным функциям уровня модуля:205206#### `wrap(text)`207208Заворачивает один абзац в *текст* (строку), так чтобы каждая строка была длиной не более [`width`](https://python-all.ru/3/library/textwrap.html#textwrap.TextWrapper.width) символов. Параметры обтекания берутся из атрибутов экземпляра `TextWrapper`. Возвращает список строк вывода, без конечных символов новой строки. Если завернутый вывод не содержит содержимого, возвращается пустой список.209210#### `fill(text)`211212Заворачивает один абзац в *текст* и возвращает одну строку, содержащую завернутый абзац.213