`textwrap.md`

154 строк · 15.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/library/textwrap.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 7.7. [`textwrap`](https://python-all.ru/2.7/library/textwrap.html#module-textwrap) – Обёртывание и заполнение текста89Новое в версии 2.3.1011**Исходный код:** [Lib/textwrap.py](https://python-all.ru/src/2.7/Lib/textwrap.py)1213---1415Модуль [`textwrap`](https://python-all.ru/2.7/library/textwrap.html#module-textwrap) предоставляет две удобные функции, [`wrap()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.wrap) и [`fill()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.fill), а также [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper), класс, который выполняет всю работу, и вспомогательную функцию [`dedent()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.dedent). Если нужно обернуть или заполнить одну-две строки, удобных функций должно быть достаточно; в противном случае для эффективности следует использовать экземпляр [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper).1617#### `textwrap.wrap(text[, width[, ...]])`1819Переносит один абзац в *text* (строке) так, чтобы каждая строка была длиной не более *width* символов. Возвращает список строк результата без завершающих символов новой строки.2021Необязательные именованные аргументы соответствуют атрибутам экземпляра [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper), описанным ниже. *width* по умолчанию равен `70`.2223См. метод [`TextWrapper.wrap()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.wrap) для дополнительных сведений о поведении [`wrap()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.wrap).2425#### `textwrap.fill(text[, width[, ...]])`2627Переносит единственный абзац в *text* и возвращает одну строку, содержащую перенесённый абзац. [`fill()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.fill) – это сокращённая форма записи для2829```python30"\n".join(wrap(text, ...))31```3233В частности, [`fill()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.fill) принимает те же именованные аргументы, что и [`wrap()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.wrap).3435И [`wrap()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.wrap), и [`fill()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.fill) работают путём создания экземпляра [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper) и вызова одного метода на нём. Этот экземпляр не используется повторно, поэтому в приложениях, которые оборачивают/заполняют много строк, эффективнее будет создать собственный объект [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper).3637Текст предпочтительно переносится по пробелам и сразу после дефисов в словах с дефисом; только после этого при необходимости разбиваются длинные слова, если только [`TextWrapper.break_long_words`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.break_long_words) не установлен в значение false.3839Дополнительная вспомогательная функция [`dedent()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.dedent) предназначена для удаления отступов из строк, содержащих нежелательные пробелы слева от текста.4041#### `textwrap.dedent(text)`4243Удаляет общие начальные пробельные символы из каждой строки в *text*.4445Это можно использовать, чтобы выровнять строки с тройными кавычками по левому краю отображения, при этом в исходном коде они остаются с отступами.4647Обратите внимание, что табуляция и пробелы считаются пробельными символами, но они не равнозначны: строки `" hello"` и `"\thello"` считаются не имеющими общего начального пробела. (Это поведение новое в Python 2.5; более старые версии этого модуля некорректно разворачивали табуляцию перед поиском общего начального пробела.)4849Строки, содержащие только пробельные символы, игнорируются во входном тексте и нормализуются до одного символа новой строки в выходном.5051Например:5253```python54def test():55    # завершите первую строку символом \, чтобы избежать пустой строки56    s = '''\57    hello58      world59    '''60    print repr(s)          # выводит '    hello\n      world\n    '61    print repr(dedent(s))  # выводит 'hello\n  world\n'62```6364#### `class textwrap.TextWrapper(...)`6566Конструктор [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper) принимает несколько необязательных именованных аргументов. Каждый аргумент соответствует одному атрибуту экземпляра, так, например6768```python69wrapper = TextWrapper(initial_indent="* ")70```7172это то же самое, что7374```python75wrapper = TextWrapper()76wrapper.initial_indent = "* "77```7879Один и тот же объект [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper) можно многократно использовать, а любые его параметры можно изменять прямым присваиванием атрибутам экземпляра между использованиями.8081Атрибуты экземпляра [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper) (и ключевые аргументы конструктора) следующие:8283#### `width`8485(по умолчанию: `70`) Максимальная длина перенесённых строк. Если во входном тексте нет отдельных слов длиннее [`width`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.width), [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper) гарантирует, что ни одна строка вывода не будет длиннее [`width`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.width) символов.8687#### `expand_tabs`8889(по умолчанию: `True`) Если true, все символы табуляции в *text* будут заменены на пробелы с помощью метода `expandtabs()` *text*.9091#### `replace_whitespace`9293(по умолчанию: `True`) Если true, после замены табуляции, но до переноса строк, метод [`wrap()`](https://python-all.ru/2.7/library/textwrap.html#textwrap.wrap) заменит каждый пробельный символ на один пробел. Заменяемыми пробельными символами являются: табуляция, новая строка, вертикальная табуляция, перевод страницы и возврат каретки (`'\t\n\v\f\r'`).9495> **Примечание**96>97> Если [`expand_tabs`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.expand_tabs) равно false, а [`replace_whitespace`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.replace_whitespace) – true, каждый символ табуляции будет заменён одним пробелом, что *не* то же самое, что и замена табуляции.9899> **Примечание**100>101> Если [`replace_whitespace`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.replace_whitespace) равно false, символы новой строки могут появляться в середине строки и приводить к странному выводу. По этой причине текст следует разбивать на абзацы (с помощью [`str.splitlines()`](https://python-all.ru/2.7/library/stdtypes.html#str.splitlines) или аналогичных средств), которые переносятся отдельно.102103#### `drop_whitespace`104105(по умолчанию: `True`) Если true, пробелы в начале и конце каждой строки (после переноса, но до добавления отступа) удаляются. Однако пробелы в начале абзаца не удаляются, если за ними следует непробельный символ. Если удаляемый пробел занимает всю строку, она удаляется целиком.106107Новое в версии 2.6: В более ранних версиях пробелы всегда удалялись.108109#### `initial_indent`110111(по умолчанию: `''`) Строка, которая будет добавлена к первой строке перенесённого вывода. Учитывается в длине первой строки. Пустая строка не добавляет отступ.112113#### `subsequent_indent`114115(по умолчанию: `''`) Строка, которая будет добавлена ко всем строкам перенесённого вывода, кроме первой. Учитывается в длине каждой строки, кроме первой.116117#### `fix_sentence_endings`118119(по умолчанию: `False`) Если true, [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper) пытается определять концы предложений и гарантирует, что предложения всегда разделяются ровно двумя пробелами. Обычно это желательно для текста в моноширинном шрифте. Однако алгоритм определения концов предложений несовершенен: он предполагает, что конец предложения состоит из строчной буквы, за которой следует один из `'.'`, `'!'` или `'?'`, возможно, за которым следует один из `'"'` или `"'"`, а затем пробел. Одна из проблем этого алгоритма в том, что он не может обнаружить разницу между «Dr.» в120121```python122[...] Dr. Frankenstein's monster [...]123```124125и «Spot.» в126127```python128[...] See Spot. See Spot run [...]129```130131[`fix_sentence_endings`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.fix_sentence_endings) по умолчанию равно false.132133Поскольку алгоритм определения предложений опирается на `string.lowercase` для определения «строчной буквы» и соглашение об использовании двух пробелов после точки для разделения предложений в одной строке, он специфичен для текстов на английском языке.134135#### `break_long_words`136137(по умолчанию: `True`) Если true, слова длиннее [`width`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.width) будут разбиты, чтобы ни одна строка не была длиннее [`width`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.width). Если false, длинные слова не разбиваются, и некоторые строки могут быть длиннее [`width`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.width). (Длинные слова будут размещены на отдельной строке, чтобы минимизировать превышение [`width`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.width).)138139#### `break_on_hyphens`140141(по умолчанию: `True`) Если true, перенос будет выполняться предпочтительно по пробелам и сразу после дефисов в составных словах, как принято в английском. Если false, только пробелы будут считаться потенциально хорошими местами для разрыва строк, но для полного запрета разрыва слов нужно установить [`break_long_words`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.break_long_words) в false. В предыдущих версиях поведение по умолчанию всегда разрешало разрыв слов с дефисом.142143Новое в версии 2.6.144145[`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper) также предоставляет два открытых метода, аналогичных удобным функциям уровня модуля:146147#### `wrap(text)`148149Заворачивает один абзац в *текст* (строку), так чтобы каждая строка была длиной не более [`width`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper.width) символов. Параметры обтекания берутся из атрибутов экземпляра [`TextWrapper`](https://python-all.ru/2.7/library/textwrap.html#textwrap.TextWrapper). Возвращает список строк вывода, без конечных символов новой строки. Если завернутый вывод не содержит содержимого, возвращается пустой список.150151#### `fill(text)`152153Заворачивает один абзац в *текст* и возвращает одну строку, содержащую завернутый абзац.154