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