formatter.md

1> **Источник:** https://python-all.ru/3.6/library/formatter.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 33.1. [`formatter`](https://python-all.ru/3.6/library/formatter.html#module-formatter) – Общее форматирование вывода89Устарело с версии 3.4: Из-за отсутствия использования модуль formatter был объявлен устаревшим.1011---1213Этот модуль поддерживает два определения интерфейса, каждое с несколькими реализациями: интерфейс *форматера* и интерфейс *объекта записи*, который требуется интерфейсу форматера.1415Объекты форматера преобразуют абстрактный поток событий форматирования в конкретные выходные события на объектах записи. Форматеры управляют несколькими стековыми структурами, чтобы различные свойства объекта записи можно было изменять и восстанавливать; объекты записи не обязаны обрабатывать относительные изменения или какие-либо операции «отката». Определенные свойства объекта записи, которыми можно управлять через объекты форматера: горизонтальное выравнивание, шрифт и отступ левого поля. Предусмотрен механизм, который также позволяет передавать объекту записи произвольные, неисключительные настройки стиля. Дополнительные интерфейсы облегчают обработку необратимых событий форматирования, таких как разделение абзацев.1617Объекты записи инкапсулируют интерфейсы устройств. Поддерживаются как абстрактные устройства (например, форматы файлов), так и физические устройства. Все предоставленные реализации работают с абстрактными устройствами. Интерфейс предоставляет механизмы для установки свойств, которыми управляют объекты форматера, и вставки данных в вывод.1819## 33.1.1. Интерфейс Formatter2021Интерфейсы для создания форматеров зависят от конкретного класса форматера, который создается. Описанные ниже интерфейсы являются обязательными, которые все форматеры должны поддерживать после инициализации.2223На уровне модуля определен один элемент данных:2425#### `formatter.AS_IS`2627Значение, которое можно использовать в спецификации шрифта, передаваемой методу `push_font()`, описанному ниже, или как новое значение для любого другого метода `push_property()`. Помещение значения `AS_IS` позволяет вызвать соответствующий метод `pop_property()`, не отслеживая, было ли изменено свойство.2829Для объектов-экземпляров форматера определены следующие атрибуты:3031#### `formatter.writer`3233Экземпляр объекта записи, с которым взаимодействует форматер.3435#### `formatter.end_paragraph(blanklines)`3637Закрывает все открытые абзацы и вставляет не менее *пустых строк* перед следующим абзацем.3839#### `formatter.add_line_break()`4041Добавляет жесткий разрыв строки, если его еще нет. Это не нарушает логический абзац.4243#### `formatter.add_hor_rule(*args, **kw)`4445Вставляет горизонтальную линию в вывод. Жесткий разрыв вставляется, если в текущем абзаце есть данные, но логический абзац не нарушается. Аргументы и ключевые слова передаются методу `send_line_break()` объекта записи.4647#### `formatter.add_flowing_data(data)`4849Предоставляет данные, которые должны быть отформатированы со схлопыванием пробельных символов. Пробелы из предыдущих и последующих вызовов [`add_flowing_data()`](https://python-all.ru/3.6/library/formatter.html#formatter.formatter.add_flowing_data) также учитываются при выполнении схлопывания. Ожидается, что данные, передаваемые этому методу, будут перенесены по словам выходным устройством. Обратите внимание, что любой перенос по словам все равно должен выполняться объектом записи, поскольку необходимо полагаться на информацию об устройстве и шрифте.5051#### `formatter.add_literal_data(data)`5253Предоставляет данные, которые должны быть переданы объекту записи без изменений. Пробелы, включая символы новой строки и табуляции, считаются допустимыми в значении *data*.5455#### `formatter.add_label_data(format, counter)`5657Вставляет метку, которая должна быть размещена слева от текущего левого поля. Используется для создания маркированных или нумерованных списков. Если значение *format* – строка, оно интерпретируется как спецификация формата для *counter*, который должен быть целым числом. Результат этого форматирования становится значением метки; если *format* не строка, оно используется как значение метки напрямую. Значение метки передается как единственный аргумент методу `send_label_data()` объекта записи. Интерпретация нестроковых значений метки зависит от соответствующего объекта записи.5859Спецификации формата – это строки, которые в сочетании со значением счетчика используются для вычисления значений меток. Каждый символ в строке формата копируется в значение метки, при этом некоторые символы распознаются как указание на преобразование значения счетчика. В частности, символ `'1'` представляет значение счетчика, отформатированное арабскими цифрами; символы `'A'` и `'a'` представляют буквенное представление значения счетчика в верхнем и нижнем регистре соответственно; а `'I'` и `'i'` представляют значение счетчика римскими цифрами в верхнем и нижнем регистре. Обратите внимание, что для буквенного и римского преобразований требуется, чтобы значение счетчика было больше нуля.6061#### `formatter.flush_softspace()`6263Отправляет все ожидающие обработки пробелы, буферизованные из предыдущего вызова [`add_flowing_data()`](https://python-all.ru/3.6/library/formatter.html#formatter.formatter.add_flowing_data), соответствующему объекту записи. Этот метод следует вызывать перед любым прямым изменением объекта записи.6465#### `formatter.push_alignment(align)`6667Помещает новую настройку выравнивания в стек выравнивания. Это может быть [`AS_IS`](https://python-all.ru/3.6/library/formatter.html#formatter.AS_IS), если изменение не требуется. Если значение выравнивания изменяется по сравнению с предыдущей настройкой, вызывается метод `new_alignment()` объекта записи со значением *align*.6869#### `formatter.pop_alignment()`7071Восстанавливает предыдущее выравнивание.7273#### `formatter.push_font((size, italic, bold, teletype))`7475Изменяет некоторые или все свойства шрифта объекта записи. Свойства, которые не установлены в [`AS_IS`](https://python-all.ru/3.6/library/formatter.html#formatter.AS_IS), устанавливаются в переданные значения, а остальные сохраняют текущие настройки. Метод `new_font()` объекта записи вызывается с полностью разрешенной спецификацией шрифта.7677#### `formatter.pop_font()`7879Восстанавливает предыдущий шрифт.8081#### `formatter.push_margin(margin)`8283Увеличивает количество отступов левого поля на единицу, связывая логический тег *margin* с новым отступом. Начальный уровень поля – `0`. Измененные значения логического тега должны быть истинными; ложные значения, отличные от [`AS_IS`](https://python-all.ru/3.6/library/formatter.html#formatter.AS_IS), недостаточны для изменения поля.8485#### `formatter.pop_margin()`8687Восстановить предыдущее поле.8889#### `formatter.push_style(*styles)`9091Добавляет произвольное количество спецификаций стилей. Все стили последовательно помещаются в стек стилей. Кортеж, представляющий весь стек, включая значения [`AS_IS`](https://python-all.ru/3.6/library/formatter.html#formatter.AS_IS), передаётся методу `new_styles()` объекта writer.9293#### `formatter.pop_style(n=1)`9495Извлекает последние *n* спецификаций стилей, переданных в [`push_style()`](https://python-all.ru/3.6/library/formatter.html#formatter.formatter.push_style). Кортеж, представляющий изменённый стек, включая значения [`AS_IS`](https://python-all.ru/3.6/library/formatter.html#formatter.AS_IS), передаётся методу `new_styles()` объекта writer.9697#### `formatter.set_spacing(spacing)`9899Устанавливает стиль межстрочных интервалов для writer.100101#### `formatter.assert_line_data(flag=1)`102103Сообщает форматировщику, что в текущий абзац были добавлены данные вне основного потока. Это следует использовать, когда writer изменялся напрямую. Необязательный аргумент *flag* можно установить в false, если в результате манипуляций с writer в конце вывода возник жёсткий разрыв строки.104105## 33.1.2. Реализации Formatter106107В этом модуле предоставлены две реализации объектов форматировщика. Большинство приложений могут использовать один из этих классов без изменений или создания подклассов.108109#### `class formatter.NullFormatter(writer=None)`110111Форматировщик, который ничего не делает. Если *writer* опущен, создаётся экземпляр [`NullWriter`](https://python-all.ru/3.6/library/formatter.html#formatter.NullWriter). Экземпляры [`NullFormatter`](https://python-all.ru/3.6/library/formatter.html#formatter.NullFormatter) не вызывают никаких методов writer. Реализации должны наследовать этот класс, если реализуют интерфейс writer, но не нуждаются в наследовании какой-либо реализации.112113#### `class formatter.AbstractFormatter(writer)`114115Стандартный форматировщик. Эта реализация показала широкую применимость для многих писателей и может использоваться напрямую в большинстве случаев. Она использовалась для реализации полнофункционального веб-браузера.116117## 33.1.3. Интерфейс Writer118119Интерфейсы для создания writer зависят от конкретного класса writer, который инстанцируется. Описанные ниже интерфейсы являются обязательными, которые все writer должны поддерживать после инициализации. Обратите внимание, что хотя большинство приложений могут использовать класс [`AbstractFormatter`](https://python-all.ru/3.6/library/formatter.html#formatter.AbstractFormatter) в качестве форматировщика, writer обычно должен предоставляться приложением.120121#### `writer.flush()`122123Сбрасывает все буферизованные выходные данные или события управления устройством.124125#### `writer.new_alignment(align)`126127Устанавливает стиль выравнивания. Значение *align* может быть любым объектом, но по соглашению это строка или `None`, где `None` указывает на использование «предпочтительного» выравнивания writer. Традиционные значения *align*: `'left'`, `'center'`, `'right'` и `'justify'`.128129#### `writer.new_font(font)`130131Устанавливает стиль шрифта. Значение *font* будет `None`, что означает использование шрифта устройства по умолчанию, или кортежем вида `(size, italic, bold, teletype)`. Размер (Size) будет строкой, указывающей размер шрифта; конкретные строки и их интерпретация должны быть определены приложением. Значения *italic*, *bold* и *teletype* – логические значения, определяющие, какие из атрибутов шрифта следует использовать.132133#### `writer.new_margin(margin, level)`134135Устанавливает уровень поля в целое число *level*, а логический тег – в *margin*. Интерпретация логического тега остаётся на усмотрение writer; единственное ограничение на значение логического тега – оно не должно быть ложным для ненулевых значений *level*.136137#### `writer.new_spacing(spacing)`138139Устанавливает стиль интервалов в *spacing*.140141#### `writer.new_styles(styles)`142143Устанавливает дополнительные стили. Значение *styles* – кортеж произвольных значений; значение [`AS_IS`](https://python-all.ru/3.6/library/formatter.html#formatter.AS_IS) следует игнорировать. Кортеж *styles* может интерпретироваться либо как набор, либо как стек в зависимости от требований приложения и реализации writer.144145#### `writer.send_line_break()`146147Разрывает текущую строку.148149#### `writer.send_paragraph(blankline)`150151Создаёт разделение абзацев как минимум на *blankline* пустых строк или эквивалент. Значение *blankline* будет целым числом. Обратите внимание, что реализация получит вызов [`send_line_break()`](https://python-all.ru/3.6/library/formatter.html#formatter.writer.send_line_break) перед этим вызовом, если требуется разрыв строки; этот метод не должен включать завершение последней строки абзаца. Он отвечает только за вертикальные интервалы между абзацами.152153#### `writer.send_hor_rule(*args, **kw)`154155Отображает горизонтальную линию на устройстве вывода. Аргументы этого метода полностью зависят от приложения и конкретного writer'а, и их следует интерпретировать с осторожностью. Реализация метода может предполагать, что перенос строки уже был сделан с помощью [`send_line_break()`](https://python-all.ru/3.6/library/formatter.html#formatter.writer.send_line_break).156157#### `writer.send_flowing_data(data)`158159Выводит символьные данные, которые при необходимости могут быть перенесены по словам и переформатированы. В любой последовательности вызовов этого метода writer может считать, что последовательности из нескольких пробелов были сжаты до одного пробела.160161#### `writer.send_literal_data(data)`162163Выводит символьные данные, уже отформатированные для отображения. Как правило, это означает, что разрывы строк, обозначенные символами новой строки, должны сохраняться, и новые разрывы строк добавляться не должны. Данные могут содержать символы новой строки и табуляции, в отличие от данных, передаваемых через интерфейс `send_formatted_data()`.164165#### `writer.send_label_data(data)`166167Устанавливает *данные* слева от текущего левого поля, если это возможно. Значение *данных* не ограничено; обработка нестроковых значений полностью зависит от приложения и writer'а. Этот метод будет вызываться только в начале строки.168169## 33.1.4. Реализации Writer170171Этот модуль предоставляет три реализации интерфейса объекта writer в качестве примеров. Большинству приложений потребуется создать собственные классы writer'а на основе класса [`NullWriter`](https://python-all.ru/3.6/library/formatter.html#formatter.NullWriter).172173#### `class formatter.NullWriter`174175Writer, который предоставляет только определение интерфейса; никаких действий над методами не выполняется. Это должен быть базовый класс для всех writer'ов, которым не нужно наследовать методы реализации.176177#### `class formatter.AbstractWriter`178179Writer, который можно использовать в отладочных форматтерах, но не более того. Каждый метод просто сообщает о себе, печатая своё имя и аргументы в стандартный вывод.180181#### `class formatter.DumbWriter(file=None, maxcol=72)`182183Простой класс writer'а, который записывает вывод в [файловый объект](https://python-all.ru/3.6/glossary.html#term-file-object), переданный как *file*, или, если *file* опущен, в стандартный вывод. Вывод просто переносится по словам на количество столбцов, заданное *maxcol*. Этот класс подходит для переформатирования последовательности абзацев.184