formatter.md

1> **Источник:** https://python-all.ru/3.0/library/formatter.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `formatter` – общее форматирование вывода89Этот модуль поддерживает два определения интерфейса, каждое с несколькими реализациями: интерфейс *форматера* и интерфейс *объекта записи*, который требуется интерфейсу форматера.1011Объекты форматера преобразуют абстрактный поток событий форматирования в конкретные выходные события на объектах записи. Форматеры управляют несколькими стековыми структурами, чтобы различные свойства объекта записи можно было изменять и восстанавливать; объекты записи не обязаны обрабатывать относительные изменения или какие-либо операции «отката». Определенные свойства объекта записи, которыми можно управлять через объекты форматера: горизонтальное выравнивание, шрифт и отступ левого поля. Предусмотрен механизм, который также позволяет передавать объекту записи произвольные, неисключительные настройки стиля. Дополнительные интерфейсы облегчают обработку необратимых событий форматирования, таких как разделение абзацев.1213Объекты записи инкапсулируют интерфейсы устройств. Поддерживаются как абстрактные устройства (например, форматы файлов), так и физические устройства. Все предоставленные реализации работают с абстрактными устройствами. Интерфейс предоставляет механизмы для установки свойств, которыми управляют объекты форматера, и вставки данных в вывод.1415## Интерфейс форматера1617Интерфейсы для создания форматеров зависят от конкретного класса форматера, который создается. Описанные ниже интерфейсы являются обязательными, которые все форматеры должны поддерживать после инициализации.1819На уровне модуля определен один элемент данных:2021#### `[formatter.AS_IS]formatter.AS_IS`2223Значение, которое может использоваться в спецификации шрифта, передаваемой методу2425`push_font()`2627, описанному ниже, или в качестве нового значения для любого другого метода2829`push_property()`3031. Передача значения3233`AS_IS`3435позволяет вызвать соответствующий метод3637`pop_property()`3839без необходимости отслеживать, было ли изменено свойство.4041Для объектов-экземпляров форматера определены следующие атрибуты:4243#### `[formatter.formatter.writer]formatter.writer`4445Экземпляр объекта записи, с которым взаимодействует форматер.4647#### `[formatter.formatter.end_paragraph]formatter.end_paragraph(blanklines)`4849Закрывает все открытые абзацы и вставляет не менее5051*пустых строк*5253перед следующим абзацем.5455#### `[formatter.formatter.add_line_break]formatter.add_line_break()`5657Добавляет жесткий разрыв строки, если его еще нет. Это не нарушает логический абзац.5859#### `[formatter.formatter.add_hor_rule]formatter.add_hor_rule(*args, **kw)`6061Вставляет горизонтальную линию в вывод. Если в текущем абзаце есть данные, вставляется жесткий разрыв, но логический абзац не разрывается. Аргументы и ключевые слова передаются методу6263`send_line_break()`6465writer'а.6667#### `[formatter.formatter.add_flowing_data]formatter.add_flowing_data(data)`6869Предоставляет данные, которые должны быть отформатированы со схлопыванием пробелов. Пробелы из предыдущих и последующих вызовов7071[`add_flowing_data()`](https://python-all.ru/3.0/library/formatter.html#formatter.formatter.add_flowing_data)7273также учитываются при схлопывании. Ожидается, что данные, переданные этому методу, будут переноситься по словам устройством вывода. Обратите внимание, что любой перенос по словам всё равно должен выполняться объектом writer из-за необходимости полагаться на информацию об устройстве и шрифте.7475#### `[formatter.formatter.add_literal_data]formatter.add_literal_data(data)`7677Предоставляет данные, которые должны быть переданы объекту записи без изменений. Пробелы, включая символы новой строки и табуляции, считаются допустимыми в значении7879*data*8081.8283#### `[formatter.formatter.add_label_data]formatter.add_label_data(format, counter)`8485Вставляет метку, которая должна быть размещена слева от текущего левого поля. Это следует использовать для построения маркированных или нумерованных списков. Если значение *format* является строкой, оно интерпретируется как спецификация формата для *counter*, который должен быть целым числом. Результат этого форматирования становится значением метки; если *format* не является строкой, оно используется как значение метки напрямую. Значение метки передаётся как единственный аргумент методу `send_label_data()` writer'а. Интерпретация нестроковых значений метки зависит от соответствующего writer'а.8687Спецификации формата – это строки, которые в сочетании со значением счётчика используются для вычисления значений меток. Каждый символ в строке формата копируется в значение метки, при этом некоторые символы распознаются как указание на преобразование значения счётчика. В частности, символ `'1'` представляет значение счётчика в виде арабского числа, символы `'A'` и `'a'` представляют алфавитные представления значения счётчика в верхнем и нижнем регистре соответственно, а `'I'` и `'i'` представляют значение счётчика римскими цифрами в верхнем и нижнем регистре. Обратите внимание, что алфавитные и римские преобразования требуют, чтобы значение счётчика было больше нуля.8889#### `[formatter.formatter.flush_softspace]formatter.flush_softspace()`9091Отправляет любые ожидающие пробелы, буферизированные от предыдущего вызова9293[`add_flowing_data()`](https://python-all.ru/3.0/library/formatter.html#formatter.formatter.add_flowing_data)9495, соответствующему объекту writer. Это следует вызывать перед любыми прямыми манипуляциями с объектом writer.9697#### `[formatter.formatter.push_alignment]formatter.push_alignment(align)`9899Помещает новую настройку выравнивания в стек выравнивания. Это может быть100101[`AS_IS`](https://python-all.ru/3.0/library/formatter.html#formatter.AS_IS)102103, если изменение не требуется. Если значение выравнивания изменено относительно предыдущей настройки, вызывается метод104105`new_alignment()`106107writer'а со значением108109*align*110111.112113#### `[formatter.formatter.pop_alignment]formatter.pop_alignment()`114115Восстанавливает предыдущее выравнивание.116117#### `[formatter.formatter.push_font]formatter.push_font((size, italic, bold, teletype))`118119Изменяет некоторые или все свойства шрифта объекта writer. Свойства, которые не установлены в120121[`AS_IS`](https://python-all.ru/3.0/library/formatter.html#formatter.AS_IS)122123, устанавливаются в переданные значения, в то время как остальные сохраняют текущие настройки. Метод124125`new_font()`126127writer'а вызывается с полностью разрешённой спецификацией шрифта.128129#### `[formatter.formatter.pop_font]formatter.pop_font()`130131Восстанавливает предыдущий шрифт.132133#### `[formatter.formatter.push_margin]formatter.push_margin(margin)`134135Увеличивает количество отступов левого поля на единицу, связывая логический тег136137*margin*138139с новым отступом. Начальный уровень поля –140141`0`142143. Изменённые значения логического тега должны быть истинными; ложные значения, отличные от144145[`AS_IS`](https://python-all.ru/3.0/library/formatter.html#formatter.AS_IS)146147, недостаточны для изменения поля.148149#### `[formatter.formatter.pop_margin]formatter.pop_margin()`150151Восстановить предыдущее поле.152153#### `[formatter.formatter.push_style]formatter.push_style(*styles)`154155Помещает произвольное количество спецификаций стиля. Все стили помещаются в стек стилей по порядку. Кортеж, представляющий весь стек, включая значения156157[`AS_IS`](https://python-all.ru/3.0/library/formatter.html#formatter.AS_IS)158159, передаётся методу160161`new_styles()`162163writer'а.164165#### `[formatter.formatter.pop_style]formatter.pop_style([n=1])`166167Извлекает последние168169*n*170171спецификаций стиля, переданных172173[`push_style()`](https://python-all.ru/3.0/library/formatter.html#formatter.formatter.push_style)174175. Кортеж, представляющий изменённый стек, включая значения176177[`AS_IS`](https://python-all.ru/3.0/library/formatter.html#formatter.AS_IS)178179, передаётся методу180181`new_styles()`182183writer'а.184185#### `[formatter.formatter.set_spacing]formatter.set_spacing(spacing)`186187Устанавливает стиль межстрочных интервалов для writer.188189#### `[formatter.formatter.assert_line_data]formatter.assert_line_data([flag=1])`190191Сообщает форматировщику, что в текущий абзац были добавлены данные вне основного потока. Это следует использовать, когда writer изменялся напрямую. Необязательный аргумент192193*flag*194195можно установить в false, если в результате манипуляций с writer в конце вывода возник жёсткий разрыв строки.196197## Реализации форматировщиков198199В этом модуле предоставлены две реализации объектов форматировщика. Большинство приложений могут использовать один из этих классов без изменений или создания подклассов.200201#### `[formatter.NullFormatter]class formatter.NullFormatter([writer])`202203Форматтер, который ничего не делает. Если параметр204205*writer*206207опущен, создаётся экземпляр208209[`NullWriter`](https://python-all.ru/3.0/library/formatter.html#formatter.NullWriter)210211. Никакие методы писателя не вызываются экземплярами212213[`NullFormatter`](https://python-all.ru/3.0/library/formatter.html#formatter.NullFormatter)214215. Реализации должны наследоваться от этого класса, если они реализуют интерфейс писателя, но не нуждаются в наследовании какой-либо реализации.216217#### `[formatter.AbstractFormatter]class formatter.AbstractFormatter(writer)`218219Стандартный форматировщик. Эта реализация показала широкую применимость для многих писателей и может использоваться напрямую в большинстве случаев. Она использовалась для реализации полнофункционального веб-браузера.220221## Интерфейс Writer222223Интерфейсы для создания писателей зависят от конкретного класса писателя, который создаётся. Описанные ниже интерфейсы являются обязательными интерфейсами, которые все писатели должны поддерживать после инициализации. Обратите внимание, что хотя большинство приложений может использовать класс [`AbstractFormatter`](https://python-all.ru/3.0/library/formatter.html#formatter.AbstractFormatter) в качестве форматтера, писатель должен обычно предоставляться приложением.224225#### `[formatter.writer.flush]writer.flush()`226227Сбрасывает все буферизованные выходные данные или события управления устройством.228229#### `[formatter.writer.new_alignment]writer.new_alignment(align)`230231Устанавливает стиль выравнивания. Значение232233*align*234235может быть любым объектом, но по соглашению является строкой или236237`None`238239, где240241`None`242243указывает, что должно использоваться «предпочтительное» выравнивание писателя. Обычные значения244245*align*246247:248249`'left'`250251,252253`'center'`254255,256257`'right'`258259и260261`'justify'`262263.264265#### `[formatter.writer.new_font]writer.new_font(font)`266267Устанавливает стиль шрифта. Значение268269*font*270271будет272273`None`274275, что указывает на необходимость использования шрифта устройства по умолчанию, или кортежем вида276277`(size, italic, bold, teletype)`278279. Параметр size будет строкой, указывающей размер шрифта; конкретные строки и их интерпретация должны быть определены приложением. Значения280281*italic*282283,284285*bold*286287и288289*teletype*290291являются логическими значениями, определяющими, какие из этих атрибутов шрифта следует использовать.292293#### `[formatter.writer.new_margin]writer.new_margin(margin, level)`294295Устанавливает уровень поля в целое число296297*level*298299, а логический тег – в300301*margin*302303. Интерпретация логического тега остаётся на усмотрение writer; единственное ограничение на значение логического тега – оно не должно быть ложным для ненулевых значений304305*level*306307.308309#### `[formatter.writer.new_spacing]writer.new_spacing(spacing)`310311Устанавливает стиль интервалов в312313*spacing*314315.316317#### `[formatter.writer.new_styles]writer.new_styles(styles)`318319Устанавливает дополнительные стили. Значение320321*styles*322323представляет собой кортеж произвольных значений; значение324325[`AS_IS`](https://python-all.ru/3.0/library/formatter.html#formatter.AS_IS)326327следует игнорировать. Кортеж328329*styles*330331может интерпретироваться либо как набор, либо как стек в зависимости от требований приложения и реализации писателя.332333#### `[formatter.writer.send_line_break]writer.send_line_break()`334335Разрывает текущую строку.336337#### `[formatter.writer.send_paragraph]writer.send_paragraph(blankline)`338339Создаёт разделение абзацев как минимум из340341*blankline*342343пустых строк или эквивалентное. Значение344345*blankline*346347будет целым числом. Обратите внимание, что реализация получит вызов348349[`send_line_break()`](https://python-all.ru/3.0/library/formatter.html#formatter.writer.send_line_break)350351перед этим вызовом, если требуется разрыв строки; этот метод не должен включать завершение последней строки абзаца. Он отвечает только за вертикальные промежутки между абзацами.352353#### `[formatter.writer.send_hor_rule]writer.send_hor_rule(*args, **kw)`354355Отображает горизонтальную линию на устройстве вывода. Аргументы этого метода полностью зависят от приложения и писателя, и должны интерпретироваться с осторожностью. Реализация метода может предполагать, что разрыв строки уже был сделан через356357[`send_line_break()`](https://python-all.ru/3.0/library/formatter.html#formatter.writer.send_line_break)358359.360361#### `[formatter.writer.send_flowing_data]writer.send_flowing_data(data)`362363Выводит символьные данные, которые при необходимости могут быть перенесены по словам и переформатированы. В любой последовательности вызовов этого метода writer может считать, что последовательности из нескольких пробелов были сжаты до одного пробела.364365#### `[formatter.writer.send_literal_data]writer.send_literal_data(data)`366367Выводит символьные данные, которые уже отформатированы для отображения. Как правило, это следует понимать так, что разрывы строк, обозначенные символами новой строки, должны сохраняться, и новые разрывы строк не должны добавляться. Данные могут содержать встроенные символы новой строки и табуляции, в отличие от данных, передаваемых интерфейсу368369`send_formatted_data()`370371.372373#### `[formatter.writer.send_label_data]writer.send_label_data(data)`374375Устанавливает376377*данные*378379слева от текущего левого поля, если это возможно. Значение380381*данных*382383не ограничено; обработка нестроковых значений полностью зависит от приложения и writer'а. Этот метод будет вызываться только в начале строки.384385## Реализации writer'а386387Три реализации интерфейса объекта писателя предоставляются в качестве примеров этим модулем. Большинству приложений потребуется создавать новые классы писателя на основе класса [`NullWriter`](https://python-all.ru/3.0/library/formatter.html#formatter.NullWriter).388389#### `[formatter.NullWriter]class formatter.NullWriter`390391Writer, который предоставляет только определение интерфейса; никаких действий над методами не выполняется. Это должен быть базовый класс для всех writer'ов, которым не нужно наследовать методы реализации.392393#### `[formatter.AbstractWriter]class formatter.AbstractWriter`394395Writer, который можно использовать в отладочных форматтерах, но не более того. Каждый метод просто сообщает о себе, печатая своё имя и аргументы в стандартный вывод.396397#### `[formatter.DumbWriter]class formatter.DumbWriter([file[, maxcol=72]])`398399Простой класс записи, который выводит данные в файловый объект, переданный как400401*file*402403или, если404405*file*406407опущен, в стандартный вывод. Вывод просто переносится по словам до количества столбцов, заданного408409*maxcol*410411. Этот класс подходит для переформатирования последовательности абзацев.412