31.1. formatter – Общее форматирование вывода¶formatter – Generic output formatting

31.1.1. Интерфейс Formatter¶The Formatter Interface

Интерфейсы для создания форматеров зависят от конкретного класса форматера, который создается. Описанные ниже интерфейсы являются обязательными, которые все форматеры должны поддерживать после инициализации.

На уровне модуля определен один элемент данных:

formatter.AS_IS¶

Значение, которое может использоваться в спецификации шрифта, передаваемой методу push_font(), описанному ниже, или в качестве нового значения для любого другого метода push_property(). Передача значения AS_IS позволяет вызвать соответствующий метод pop_property() без необходимости отслеживать, было ли изменено свойство.

Для объектов-экземпляров форматера определены следующие атрибуты:

formatter.writer¶

Экземпляр объекта записи, с которым взаимодействует форматер.

formatter.end_paragraph(blanklines)¶

Закрывает все открытые абзацы и вставляет не менее пустых строк перед следующим абзацем.

formatter.add_line_break()¶

Добавляет жесткий разрыв строки, если его еще нет. Это не нарушает логический абзац.

formatter.add_hor_rule(*args, **kw)¶

Вставляет горизонтальную линию в вывод. Если в текущем абзаце есть данные, вставляется жесткий разрыв, но логический абзац не разрывается. Аргументы и ключевые слова передаются методу send_line_break() writer'а.

formatter.add_flowing_data(data)¶

Предоставляет данные, которые должны быть отформатированы со схлопыванием пробелов. Пробелы из предыдущих и последующих вызовов add_flowing_data() также учитываются при схлопывании. Ожидается, что данные, переданные этому методу, будут переноситься по словам устройством вывода. Обратите внимание, что любой перенос по словам всё равно должен выполняться объектом writer из-за необходимости полагаться на информацию об устройстве и шрифте.

formatter.add_literal_data(data)¶

Предоставляет данные, которые должны быть переданы объекту записи без изменений. Пробелы, включая символы новой строки и табуляции, считаются допустимыми в значении data.

formatter.add_label_data(format, counter)¶

Вставляет метку, которая должна быть размещена слева от текущего левого поля. Это следует использовать для построения маркированных или нумерованных списков. Если значение format является строкой, оно интерпретируется как спецификация формата для counter, который должен быть целым числом. Результат этого форматирования становится значением метки; если format не является строкой, оно используется как значение метки напрямую. Значение метки передаётся как единственный аргумент методу send_label_data() writer'а. Интерпретация нестроковых значений метки зависит от соответствующего writer'а.

Спецификации формата – это строки, которые в сочетании со значением счётчика используются для вычисления значений меток. Каждый символ в строке формата копируется в значение метки, при этом некоторые символы распознаются как указание на преобразование значения счётчика. В частности, символ '1' представляет значение счётчика в виде арабского числа, символы 'A' и 'a' представляют алфавитные представления значения счётчика в верхнем и нижнем регистре соответственно, а 'I' и 'i' представляют значение счётчика римскими цифрами в верхнем и нижнем регистре. Обратите внимание, что алфавитные и римские преобразования требуют, чтобы значение счётчика было больше нуля.

formatter.flush_softspace()¶

Отправляет любые ожидающие пробелы, буферизированные от предыдущего вызова add_flowing_data(), соответствующему объекту writer. Это следует вызывать перед любыми прямыми манипуляциями с объектом writer.

formatter.push_alignment(align)¶

Помещает новую настройку выравнивания в стек выравнивания. Это может быть AS_IS, если изменение не требуется. Если значение выравнивания изменено относительно предыдущей настройки, вызывается метод new_alignment() writer'а со значением align.

formatter.pop_alignment()¶

Восстанавливает предыдущее выравнивание.

formatter.push_font((size, italic, bold, teletype))¶

Изменяет некоторые или все свойства шрифта объекта writer. Свойства, которые не установлены в AS_IS, устанавливаются в переданные значения, в то время как остальные сохраняют текущие настройки. Метод new_font() writer'а вызывается с полностью разрешённой спецификацией шрифта.

formatter.pop_font()¶

Восстанавливает предыдущий шрифт.

formatter.push_margin(margin)¶

Увеличивает количество отступов левого поля на единицу, связывая логический тег margin с новым отступом. Начальный уровень поля – 0. Изменённые значения логического тега должны быть истинными; ложные значения, отличные от AS_IS, недостаточны для изменения поля.

formatter.pop_margin()¶

Восстановить предыдущее поле.

formatter.push_style(*styles)¶

Помещает произвольное количество спецификаций стиля. Все стили помещаются в стек стилей по порядку. Кортеж, представляющий весь стек, включая значения AS_IS, передаётся методу new_styles() writer'а.

formatter.pop_style(n=1)¶

Извлекает последние n спецификаций стиля, переданных push_style(). Кортеж, представляющий изменённый стек, включая значения AS_IS, передаётся методу new_styles() writer'а.

formatter.set_spacing(spacing)¶

Устанавливает стиль межстрочных интервалов для writer.

formatter.assert_line_data(flag=1)¶

Сообщает форматировщику, что в текущий абзац были добавлены данные вне основного потока. Это следует использовать, когда writer изменялся напрямую. Необязательный аргумент flag можно установить в false, если в результате манипуляций с writer в конце вывода возник жёсткий разрыв строки.

31.1.2. Реализации Formatter¶Formatter Implementations

В этом модуле предоставлены две реализации объектов форматировщика. Большинство приложений могут использовать один из этих классов без изменений или создания подклассов.

class formatter.NullFormatter(writer=None)¶

Форматтер, который ничего не делает. Если параметр writer опущен, создаётся экземпляр NullWriter. Никакие методы писателя не вызываются экземплярами NullFormatter. Реализации должны наследоваться от этого класса, если они реализуют интерфейс писателя, но не нуждаются в наследовании какой-либо реализации.

class formatter.AbstractFormatter(writer)¶

Стандартный форматировщик. Эта реализация показала широкую применимость для многих писателей и может использоваться напрямую в большинстве случаев. Она использовалась для реализации полнофункционального веб-браузера.

31.1.3. Интерфейс Writer¶The Writer Interface

Интерфейсы для создания писателей зависят от конкретного класса писателя, который создаётся. Описанные ниже интерфейсы являются обязательными интерфейсами, которые все писатели должны поддерживать после инициализации. Обратите внимание, что хотя большинство приложений может использовать класс AbstractFormatter в качестве форматтера, писатель должен обычно предоставляться приложением.

writer.flush()¶

Сбрасывает все буферизованные выходные данные или события управления устройством.

writer.new_alignment(align)¶

Устанавливает стиль выравнивания. Значение align может быть любым объектом, но по соглашению является строкой или None, где None указывает, что должно использоваться «предпочтительное» выравнивание писателя. Обычные значения align: 'left', 'center', 'right' и 'justify'.

writer.new_font(font)¶

Устанавливает стиль шрифта. Значение font будет None, что указывает на необходимость использования шрифта устройства по умолчанию, или кортежем вида (size, italic, bold, teletype). Параметр size будет строкой, указывающей размер шрифта; конкретные строки и их интерпретация должны быть определены приложением. Значения italic, bold и teletype являются логическими значениями, определяющими, какие из этих атрибутов шрифта следует использовать.

writer.new_margin(margin, level)¶

Устанавливает уровень поля в целое число level, а логический тег – в margin. Интерпретация логического тега остаётся на усмотрение writer; единственное ограничение на значение логического тега – оно не должно быть ложным для ненулевых значений level.

writer.new_spacing(spacing)¶

Устанавливает стиль интервалов в spacing.

writer.new_styles(styles)¶

Устанавливает дополнительные стили. Значение styles представляет собой кортеж произвольных значений; значение AS_IS следует игнорировать. Кортеж styles может интерпретироваться либо как набор, либо как стек в зависимости от требований приложения и реализации писателя.

writer.send_line_break()¶

Разрывает текущую строку.

writer.send_paragraph(blankline)¶

Создаёт разделение абзацев как минимум из blankline пустых строк или эквивалентное. Значение blankline будет целым числом. Обратите внимание, что реализация получит вызов send_line_break() перед этим вызовом, если требуется разрыв строки; этот метод не должен включать завершение последней строки абзаца. Он отвечает только за вертикальные промежутки между абзацами.

writer.send_hor_rule(*args, **kw)¶

Отображает горизонтальную линию на устройстве вывода. Аргументы этого метода полностью зависят от приложения и писателя, и должны интерпретироваться с осторожностью. Реализация метода может предполагать, что разрыв строки уже был сделан через send_line_break().

writer.send_flowing_data(data)¶

Выводит символьные данные, которые при необходимости могут быть перенесены по словам и переформатированы. В любой последовательности вызовов этого метода writer может считать, что последовательности из нескольких пробелов были сжаты до одного пробела.

writer.send_literal_data(data)¶

Выводит символьные данные, которые уже отформатированы для отображения. Как правило, это следует понимать так, что разрывы строк, обозначенные символами новой строки, должны сохраняться, и новые разрывы строк не должны добавляться. Данные могут содержать встроенные символы новой строки и табуляции, в отличие от данных, передаваемых интерфейсу send_formatted_data().

writer.send_label_data(data)¶

Устанавливает данные слева от текущего левого поля, если это возможно. Значение данных не ограничено; обработка нестроковых значений полностью зависит от приложения и writer'а. Этот метод будет вызываться только в начале строки.

31.1.4. Реализации Writer¶Writer Implementations

Три реализации интерфейса объекта писателя предоставляются в качестве примеров этим модулем. Большинству приложений потребуется создавать новые классы писателя на основе класса NullWriter.

class formatter.NullWriter¶

Writer, который предоставляет только определение интерфейса; никаких действий над методами не выполняется. Это должен быть базовый класс для всех writer'ов, которым не нужно наследовать методы реализации.

class formatter.AbstractWriter¶

Writer, который можно использовать в отладочных форматтерах, но не более того. Каждый метод просто сообщает о себе, печатая своё имя и аргументы в стандартный вывод.

class formatter.DumbWriter(file=None, maxcol=72)¶

Простой класс writer'а, который записывает вывод в файловый объект, переданный как file, или, если file опущен, в стандартный вывод. Вывод просто переносится по словам на количество столбцов, заданное maxcol. Этот класс подходит для переформатирования последовательности абзацев.