2
:mod:`formatter` --- Generic output formatting
3
==============================================
6
:synopsis: Generic output formatter and device interface.
9
.. index:: single: HTMLParser (class in htmllib)
11
This module supports two interface definitions, each with multiple
12
implementations. The *formatter* interface is used by the :class:`HTMLParser`
13
class of the :mod:`htmllib` module, and the *writer* interface is required by
14
the formatter interface.
16
Formatter objects transform an abstract flow of formatting events into specific
17
output events on writer objects. Formatters manage several stack structures to
18
allow various properties of a writer object to be changed and restored; writers
19
need not be able to handle relative changes nor any sort of "change back"
20
operation. Specific writer properties which may be controlled via formatter
21
objects are horizontal alignment, font, and left margin indentations. A
22
mechanism is provided which supports providing arbitrary, non-exclusive style
23
settings to a writer as well. Additional interfaces facilitate formatting
24
events which are not reversible, such as paragraph separation.
26
Writer objects encapsulate device interfaces. Abstract devices, such as file
27
formats, are supported as well as physical devices. The provided
28
implementations all work with abstract devices. The interface makes available
29
mechanisms for setting the properties which formatter objects manage and
30
inserting data into the output.
33
.. _formatter-interface:
35
The Formatter Interface
36
-----------------------
38
Interfaces to create formatters are dependent on the specific formatter class
39
being instantiated. The interfaces described below are the required interfaces
40
which all formatters must support once initialized.
42
One data element is defined at the module level:
47
Value which can be used in the font specification passed to the ``push_font()``
48
method described below, or as the new value to any other ``push_property()``
49
method. Pushing the ``AS_IS`` value allows the corresponding ``pop_property()``
50
method to be called without having to track whether the property was changed.
52
The following attributes are defined for formatter instance objects:
55
.. attribute:: formatter.writer
57
The writer instance with which the formatter interacts.
60
.. method:: formatter.end_paragraph(blanklines)
62
Close any open paragraphs and insert at least *blanklines* before the next
66
.. method:: formatter.add_line_break()
68
Add a hard line break if one does not already exist. This does not break the
72
.. method:: formatter.add_hor_rule(*args, **kw)
74
Insert a horizontal rule in the output. A hard break is inserted if there is
75
data in the current paragraph, but the logical paragraph is not broken. The
76
arguments and keywords are passed on to the writer's :meth:`send_line_break`
80
.. method:: formatter.add_flowing_data(data)
82
Provide data which should be formatted with collapsed whitespace. Whitespace
83
from preceding and successive calls to :meth:`add_flowing_data` is considered as
84
well when the whitespace collapse is performed. The data which is passed to
85
this method is expected to be word-wrapped by the output device. Note that any
86
word-wrapping still must be performed by the writer object due to the need to
87
rely on device and font information.
90
.. method:: formatter.add_literal_data(data)
92
Provide data which should be passed to the writer unchanged. Whitespace,
93
including newline and tab characters, are considered legal in the value of
97
.. method:: formatter.add_label_data(format, counter)
99
Insert a label which should be placed to the left of the current left margin.
100
This should be used for constructing bulleted or numbered lists. If the
101
*format* value is a string, it is interpreted as a format specification for
102
*counter*, which should be an integer. The result of this formatting becomes the
103
value of the label; if *format* is not a string it is used as the label value
104
directly. The label value is passed as the only argument to the writer's
105
:meth:`send_label_data` method. Interpretation of non-string label values is
106
dependent on the associated writer.
108
Format specifications are strings which, in combination with a counter value,
109
are used to compute label values. Each character in the format string is copied
110
to the label value, with some characters recognized to indicate a transform on
111
the counter value. Specifically, the character ``'1'`` represents the counter
112
value formatter as an Arabic number, the characters ``'A'`` and ``'a'``
113
represent alphabetic representations of the counter value in upper and lower
114
case, respectively, and ``'I'`` and ``'i'`` represent the counter value in Roman
115
numerals, in upper and lower case. Note that the alphabetic and roman
116
transforms require that the counter value be greater than zero.
119
.. method:: formatter.flush_softspace()
121
Send any pending whitespace buffered from a previous call to
122
:meth:`add_flowing_data` to the associated writer object. This should be called
123
before any direct manipulation of the writer object.
126
.. method:: formatter.push_alignment(align)
128
Push a new alignment setting onto the alignment stack. This may be
129
:const:`AS_IS` if no change is desired. If the alignment value is changed from
130
the previous setting, the writer's :meth:`new_alignment` method is called with
134
.. method:: formatter.pop_alignment()
136
Restore the previous alignment.
139
.. method:: formatter.push_font((size, italic, bold, teletype))
141
Change some or all font properties of the writer object. Properties which are
142
not set to :const:`AS_IS` are set to the values passed in while others are
143
maintained at their current settings. The writer's :meth:`new_font` method is
144
called with the fully resolved font specification.
147
.. method:: formatter.pop_font()
149
Restore the previous font.
152
.. method:: formatter.push_margin(margin)
154
Increase the number of left margin indentations by one, associating the logical
155
tag *margin* with the new indentation. The initial margin level is ``0``.
156
Changed values of the logical tag must be true values; false values other than
157
:const:`AS_IS` are not sufficient to change the margin.
160
.. method:: formatter.pop_margin()
162
Restore the previous margin.
165
.. method:: formatter.push_style(*styles)
167
Push any number of arbitrary style specifications. All styles are pushed onto
168
the styles stack in order. A tuple representing the entire stack, including
169
:const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method.
172
.. method:: formatter.pop_style([n=1])
174
Pop the last *n* style specifications passed to :meth:`push_style`. A tuple
175
representing the revised stack, including :const:`AS_IS` values, is passed to
176
the writer's :meth:`new_styles` method.
179
.. method:: formatter.set_spacing(spacing)
181
Set the spacing style for the writer.
184
.. method:: formatter.assert_line_data([flag=1])
186
Inform the formatter that data has been added to the current paragraph
187
out-of-band. This should be used when the writer has been manipulated
188
directly. The optional *flag* argument can be set to false if the writer
189
manipulations produced a hard line break at the end of the output.
194
Formatter Implementations
195
-------------------------
197
Two implementations of formatter objects are provided by this module. Most
198
applications may use one of these classes without modification or subclassing.
201
.. class:: NullFormatter([writer])
203
A formatter which does nothing. If *writer* is omitted, a :class:`NullWriter`
204
instance is created. No methods of the writer are called by
205
:class:`NullFormatter` instances. Implementations should inherit from this
206
class if implementing a writer interface but don't need to inherit any
210
.. class:: AbstractFormatter(writer)
212
The standard formatter. This implementation has demonstrated wide applicability
213
to many writers, and may be used directly in most circumstances. It has been
214
used to implement a full-featured World Wide Web browser.
217
.. _writer-interface:
222
Interfaces to create writers are dependent on the specific writer class being
223
instantiated. The interfaces described below are the required interfaces which
224
all writers must support once initialized. Note that while most applications can
225
use the :class:`AbstractFormatter` class as a formatter, the writer must
226
typically be provided by the application.
229
.. method:: writer.flush()
231
Flush any buffered output or device control events.
234
.. method:: writer.new_alignment(align)
236
Set the alignment style. The *align* value can be any object, but by convention
237
is a string or ``None``, where ``None`` indicates that the writer's "preferred"
238
alignment should be used. Conventional *align* values are ``'left'``,
239
``'center'``, ``'right'``, and ``'justify'``.
242
.. method:: writer.new_font(font)
244
Set the font style. The value of *font* will be ``None``, indicating that the
245
device's default font should be used, or a tuple of the form ``(size,
246
italic, bold, teletype)``. Size will be a string indicating the size of
247
font that should be used; specific strings and their interpretation must be
248
defined by the application. The *italic*, *bold*, and *teletype* values are
249
Boolean values specifying which of those font attributes should be used.
252
.. method:: writer.new_margin(margin, level)
254
Set the margin level to the integer *level* and the logical tag to *margin*.
255
Interpretation of the logical tag is at the writer's discretion; the only
256
restriction on the value of the logical tag is that it not be a false value for
257
non-zero values of *level*.
260
.. method:: writer.new_spacing(spacing)
262
Set the spacing style to *spacing*.
265
.. method:: writer.new_styles(styles)
267
Set additional styles. The *styles* value is a tuple of arbitrary values; the
268
value :const:`AS_IS` should be ignored. The *styles* tuple may be interpreted
269
either as a set or as a stack depending on the requirements of the application
270
and writer implementation.
273
.. method:: writer.send_line_break()
275
Break the current line.
278
.. method:: writer.send_paragraph(blankline)
280
Produce a paragraph separation of at least *blankline* blank lines, or the
281
equivalent. The *blankline* value will be an integer. Note that the
282
implementation will receive a call to :meth:`send_line_break` before this call
283
if a line break is needed; this method should not include ending the last line
284
of the paragraph. It is only responsible for vertical spacing between
288
.. method:: writer.send_hor_rule(*args, **kw)
290
Display a horizontal rule on the output device. The arguments to this method
291
are entirely application- and writer-specific, and should be interpreted with
292
care. The method implementation may assume that a line break has already been
293
issued via :meth:`send_line_break`.
296
.. method:: writer.send_flowing_data(data)
298
Output character data which may be word-wrapped and re-flowed as needed. Within
299
any sequence of calls to this method, the writer may assume that spans of
300
multiple whitespace characters have been collapsed to single space characters.
303
.. method:: writer.send_literal_data(data)
305
Output character data which has already been formatted for display. Generally,
306
this should be interpreted to mean that line breaks indicated by newline
307
characters should be preserved and no new line breaks should be introduced. The
308
data may contain embedded newline and tab characters, unlike data provided to
309
the :meth:`send_formatted_data` interface.
312
.. method:: writer.send_label_data(data)
314
Set *data* to the left of the current left margin, if possible. The value of
315
*data* is not restricted; treatment of non-string values is entirely
316
application- and writer-dependent. This method will only be called at the
322
Writer Implementations
323
----------------------
325
Three implementations of the writer object interface are provided as examples by
326
this module. Most applications will need to derive new writer classes from the
327
:class:`NullWriter` class.
330
.. class:: NullWriter()
332
A writer which only provides the interface definition; no actions are taken on
333
any methods. This should be the base class for all writers which do not need to
334
inherit any implementation methods.
337
.. class:: AbstractWriter()
339
A writer which can be used in debugging formatters, but not much else. Each
340
method simply announces itself by printing its name and arguments on standard
344
.. class:: DumbWriter(file=None, maxcol=72)
346
Simple writer class which writes output on the file object passed in as *file*
347
or, if *file* is None, on standard output. The output is simply word-wrapped
348
to the number of columns specified by *maxcol*. This class is suitable for
349
reflowing a sequence of paragraphs.
added
removed
python-2.7.11-docs-html/_sources/library/formatter.txt
