textwrap.md
1> **Источник:** https://python-all.ru/3.3/library/textwrap.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 6.4. [`textwrap`](https://python-all.ru/3.3/library/textwrap.html#module-textwrap) – Перенос и заполнение текста89**Исходный код:** [Lib/textwrap.py](https://python-all.ru/src/3.3/Lib/textwrap.py)1011---1213The [`textwrap`](https://python-all.ru/3.3/library/textwrap.html#module-textwrap) module provides two convenience functions, [`wrap()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.wrap) and [`fill()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.fill), as well as [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper), the class that does all the work, and two utility functions, [`dedent()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.dedent) and [`indent()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.indent). If you’re just wrapping or filling one or two text strings, the convenience functions should be good enough; otherwise, you should use an instance of [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper) for efficiency.1415#### `textwrap.wrap(text, width=70, **kwargs)`1617Переносит единственный абзац в *text* (строку) так, что каждая строка не длиннее *width* символов. Возвращает список выходных строк, без завершающих символов новой строки.1819Необязательные именованные аргументы соответствуют атрибутам экземпляра [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper), описанным ниже. *width* по умолчанию равен `70`.2021Дополнительные сведения о поведении [`wrap()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.wrap) см. в описании метода [`TextWrapper.wrap()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.wrap).2223#### `textwrap.fill(text, width=70, **kwargs)`2425Обёртывает единственный абзац в *text* и возвращает одну строку, содержащую обёрнутый абзац. [`fill()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.fill) – это сокращённая запись для2627```python28"\n".join(wrap(text, ...))29```3031В частности, [`fill()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.fill) принимает те же именованные аргументы, что и [`wrap()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.wrap).3233И [`wrap()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.wrap), и [`fill()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.fill) работают, создавая экземпляр [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper) и вызывая на нём один метод. Этот экземпляр не переиспользуется, поэтому для приложений, которые переносят/заполняют много текстовых строк, будет эффективнее создать собственный объект [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper).3435Текст предпочтительно переносится по пробелам и сразу после дефисов в составных словах; только в этом случае длинные слова будут разбиты при необходимости, если [`TextWrapper.break_long_words`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.break_long_words) не установлено в false.3637Две дополнительные вспомогательные функции, [`dedent()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.dedent) и [`indent()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.indent), предоставляются для удаления отступов из строк, содержащих нежелательные пробелы слева от текста, и для добавления произвольного префикса к выбранным строкам в блоке текста.3839#### `textwrap.dedent(text)`4041Удаляет общие начальные пробельные символы из каждой строки в *text*.4243Это можно использовать, чтобы выровнять строки с тройными кавычками по левому краю отображения, при этом в исходном коде они остаются с отступами.4445Обратите внимание, что табуляции и пробелы оба считаются пробельными символами, но они не равны: строки `" hello"` и `"\thello"` считаются не имеющими общего начального пробела.4647Например:4849```python50def test():51 # завершите первую строку символом \, чтобы избежать пустой строки52 s = '''\53 hello54 world55 '''56 print(repr(s)) # выводит ' hello\n world\n '57 print(repr(dedent(s))) # выводит 'hello\n world\n'58```5960#### `textwrap.indent(text, prefix, predicate=None)`6162Добавляет *prefix* в начало выбранных строк в *text*.6364Строки разделяются вызовом `text.splitlines(True)`.6566По умолчанию *prefix* добавляется ко всем строкам, не состоящим только из пробельных символов (включая концы строк).6768Например:6970```python71>>> s = 'hello\n\n \nworld'72>>> indent(s, ' ')73' hello\n\n \n world'74```7576Необязательный аргумент *predicate* можно использовать для управления тем, какие строки получают отступ. Например, легко добавить *prefix* даже к пустым строкам и строкам, состоящим только из пробелов:7778```python79>>> print(indent(s, '+ ', lambda line: True))80+ hello81+82+83+ world84```8586#### `class textwrap.TextWrapper(**kwargs)`8788Конструктор [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper) принимает ряд необязательных именованных аргументов. Каждый именованный аргумент соответствует атрибуту экземпляра, так, например,8990```python91wrapper = TextWrapper(initial_indent="* ")92```9394это то же самое, что9596```python97wrapper = TextWrapper()98wrapper.initial_indent = "* "99```100101Можно повторно использовать один и тот же объект [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper) много раз, и между использованиями можно изменять любые его параметры прямым присваиванием атрибутам экземпляра.102103Атрибуты экземпляра [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper) (и именованные аргументы конструктора) следующие:104105#### `width`106107(по умолчанию: `70`) Максимальная длина переносимых строк. Пока во входном тексте нет отдельных слов длиннее [`width`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.width), [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper) гарантирует, что ни одна строка вывода не будет длиннее [`width`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.width) символов.108109#### `expand_tabs`110111(по умолчанию: `True`) Если истинно, то все символы табуляции в *text* будут заменены на пробелы с использованием метода `expandtabs()` строки *text*.112113#### `tabsize`114115(по умолчанию: `8`) Если [`expand_tabs`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.expand_tabs) истинно, то все символы табуляции в *text* будут заменены на ноль или более пробелов в зависимости от текущей колонки и указанного размера табуляции.116117Новое в версии 3.3.118119#### `replace_whitespace`120121(по умолчанию: `True`) Если истинно, то после замены табуляции, но до переноса, метод [`wrap()`](https://python-all.ru/3.3/library/textwrap.html#textwrap.wrap) заменит каждый пробельный символ на один пробел. Заменяются следующие пробельные символы: табуляция, новая строка, вертикальная табуляция, прогон страницы и возврат каретки (`'\t\n\v\f\r'`).122123> **Примечание**124>125> Если [`expand_tabs`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.expand_tabs) ложно, а [`replace_whitespace`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.replace_whitespace) истинно, то каждый символ табуляции будет заменён одним пробелом, что *не* то же самое, что замена табуляции.126127> **Примечание**128>129> Если [`replace_whitespace`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.replace_whitespace) ложно, символы новой строки могут оказаться в середине строки и привести к странному выводу. По этой причине текст следует разбивать на абзацы (с помощью [`str.splitlines()`](https://python-all.ru/3.3/library/stdtypes.html#str.splitlines) или аналогично), которые переносятся отдельно.130131#### `drop_whitespace`132133(по умолчанию: `True`) Если true, то пробелы в начале и конце каждой строки (после переноса, но до отступа) удаляются. Однако пробелы в начале абзаца не удаляются, если за ними следует непробельный символ. Если удаляемые пробелы занимают целую строку, то вся строка удаляется.134135#### `initial_indent`136137(по умолчанию: `''`) Строка, которая будет добавлена к первой строке перенесённого вывода. Учитывается в длине первой строки. Пустая строка не добавляет отступ.138139#### `subsequent_indent`140141(по умолчанию: `''`) Строка, которая будет добавлена ко всем строкам перенесённого вывода, кроме первой. Учитывается в длине каждой строки, кроме первой.142143#### `fix_sentence_endings`144145(по умолчанию: `False`) Если true, [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper) пытается обнаружить концы предложений и гарантировать, что предложения всегда разделяются ровно двумя пробелами. Обычно это желательно для текста моноширинным шрифтом. Однако алгоритм обнаружения предложений несовершенен: он предполагает, что конец предложения состоит из строчной буквы, за которой следует один из `'.'`, `'!'` или `'?'`, возможно, за которым следует один из `'"'` или `"'"`, за которым следует пробел. Одна из проблем этого алгоритма заключается в том, что он не может различить «Dr.» в146147```python148[...] Dr. Frankenstein's monster [...]149```150151и «Spot.» в152153```python154[...] See Spot. See Spot run [...]155```156157[`fix_sentence_endings`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.fix_sentence_endings) по умолчанию false.158159Поскольку алгоритм обнаружения предложений полагается на `string.lowercase` для определения «строчной буквы» и соглашение об использовании двух пробелов после точки для разделения предложений на одной строке, он применим только к текстам на английском языке.160161#### `break_long_words`162163(по умолчанию: `True`) Если true, то слова длиннее [`width`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.width) будут разрываться, чтобы гарантировать, что ни одна строка не длиннее [`width`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.width). Если false, длинные слова не будут разрываться, и некоторые строки могут оказаться длиннее [`width`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.width). (Длинные слова будут помещаться на отдельную строку, чтобы минимизировать превышение [`width`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.width).)164165#### `break_on_hyphens`166167(по умолчанию: `True`) Если true, перенос будет выполняться предпочтительно по пробелам и сразу после дефисов в составных словах, как это принято в английском языке. Если false, только пробелы будут считаться потенциально хорошими местами для разрыва строк, но необходимо установить [`break_long_words`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.break_long_words) в false, если требуются действительно неразрывные слова. Поведение по умолчанию в предыдущих версиях заключалось в том, чтобы всегда разрешать разрыв слов с дефисом.168169[`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper) также предоставляет два открытых метода, аналогичных модульным удобным функциям:170171#### `wrap(text)`172173Переносит один абзац в *text* (строка) так, чтобы каждая строка имела длину не более [`width`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper.width) символов. Все параметры переноса берутся из атрибутов экземпляра [`TextWrapper`](https://python-all.ru/3.3/library/textwrap.html#textwrap.TextWrapper). Возвращает список строк вывода без завершающих символов новой строки. Если перенесённый вывод не содержит содержимого, возвращается пустой список.174175#### `fill(text)`176177Заворачивает один абзац в *текст* и возвращает одну строку, содержащую завернутый абзац.178