formatter — Общее форматирование вывода

Не рекомендуется, начиная с версии 3.4: Из-за отсутствия использования модуль formatter устарел.


Данный модуль поддерживает два определения интерфейса, у каждого из которых несколько реализаций: интерфейс formatter и интерфейс writer, который требуется интерфейсу форматирования.

Объекты форматирования преобразуют абстрактный поток событий форматирования в определённые выходные события на объектах записи. Форматтеры управляют несколькими структурами стека, чтобы позволить изменять и восстанавливать различные свойства объекта записи; писатели не должны иметь возможность обрабатывать относительные изменения или какие-либо операции «возврата назад». Конкретными свойствами средства записи, которыми можно управлять с помощью объектов форматтера, являются горизонтальное выравнивание, шрифт и отступы левого поля. Предоставляется механизм, который также поддерживает предоставление произвольных, неэксклюзивных настроек стиля писателю. Дополнительные интерфейсы облегчают необратимые события форматирования, такие как разделение абзацев.

Объекты Writer инкапсулируют интерфейсы устройств. Абстрактные устройства, такие как форматы файлов, поддерживаются так же, как и физические устройства. Все предоставленные реализации работают с абстрактными устройствами. Интерфейс предоставляет механизмы для установки свойств, которыми управляют объекты форматтера, и вставки данных в вывод.

Интерфейс форматирования

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

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

formatter.AS_IS

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

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

formatter.writer

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

formatter.end_paragraph(blanklines)

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

formatter.add_line_break()

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

formatter.add_hor_rule(*args, **kw)

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

formatter.add_flowing_data(data)

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

formatter.add_literal_data(data)

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

formatter.add_label_data(format, counter)

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

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

formatter.flush_softspace()

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

formatter.push_alignment(align)

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

formatter.pop_alignment()

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

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

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

formatter.pop_font()

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

formatter.push_margin(margin)

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

formatter.pop_margin()

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

formatter.push_style(*styles)

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

formatter.pop_style(n=1)

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

formatter.set_spacing(spacing)

Устанавливает стиль интервала для писателя.

formatter.assert_line_data(flag=1)

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

Реализации форматтера

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

class formatter.NullFormatter(writer=None)

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

class formatter.AbstractFormatter(writer)

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

Интерфейс писателя

Интерфейсы для создания модулей писателей зависят от конкретного создаваемого класса модуля писателя. Интерфейсы, описанные ниже, являются обязательными интерфейсами, которые все модули записи должны поддерживать после инициализации. Обратите внимание, что хотя большинство приложений могут использовать класс 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). Размер будет строкой, указывающей размер шрифта, который следует использовать; конкретные строки и их интерпретация должны определяться приложением. Значения italic, bold и teletype являются логическими значениями, указывающими, какой из данных атрибутов шрифта следует использовать.

writer.new_margin(margin, level)

Устанавливает уровень поля на целое число level и логический тег на margin. Интерпретация логического тега остаётся на усмотрение автора; единственное ограничение на значение логического тега состоит в том, что оно не может быть ложным для ненулевых значений 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.send_literal_data(data)

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

writer.send_label_data(data)

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

Реализации писателя

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

class formatter.NullWriter

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

class formatter.AbstractWriter

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

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

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