formatter ---通用输出格式

3.4 版后已移除: 由于缺乏使用，格式化程序模块已被弃用。

---

此模块支持两个接口定义，每个接口定义都有多个实现： 格式化程序 接口，以及*writer*格式化程序接口所需的接口。

格式化程序对象将格式化事件的抽象流转换为写入程序对象上的特定输出事件。格式化程序管理多个堆栈结构，以允许更改和还原写入程序对象的各种属性；写入程序不需要能够处理相对更改，也不需要任何类型的“更改回”操作。可通过格式化程序对象控制的特定写入程序属性包括水平对齐、字体和左边缘缩进。提供了一种支持为编写器提供任意、非独占样式设置的机制。附加接口有助于格式化不可逆的事件，如段落分离。

编写器对象封装设备接口。支持抽象设备（如文件格式）和物理设备。提供的实现都与抽象设备一起工作。该接口提供了设置格式化程序对象管理的属性以及将数据插入输出的机制。

格式化程序接口

创建格式化程序的接口依赖于正在实例化的特定格式化程序类。下面描述的接口是所有格式化程序在初始化后必须支持的必需接口。

在模块级定义一个数据元素：

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() 方法。

formatter.add_flowing_data(data)

提供应使用折叠空格格式化的数据。前一个和连续调用的空格 add_flowing_data() 在执行空白折叠时也会考虑。传递给此方法的数据将由输出设备进行换行。请注意，由于需要依赖设备和字体信息，因此编写器对象仍然必须执行任何换行操作。

formatter.add_literal_data(data)

提供应以不变方式传递给编写器的数据。空格，包括换行符和制表符，在 data .

formatter.add_label_data(format, counter)

插入一个标签，该标签应放在当前左边距的左侧。这应该用于构建项目符号列表或编号列表。如果 格式 值是一个字符串，它被解释为 柜台 ，应为整数。此格式的结果将成为标签的值；如果 格式 不是字符串，它直接用作标签值。标签值作为唯一的参数传递给编写器的 send_label_data() 方法。非字符串标签值的解释取决于关联的编写器。

格式规范是字符串，与计数器值一起用于计算标签值。格式字符串中的每个字符都被复制到标签值，并识别出一些字符，以指示计数器值上的转换。具体来说，角色 '1' 将计数器值格式化程序表示为阿拉伯数字，字符 'A' 和 'a' 分别用大写和小写表示计数器值的字母表示，和 'I' 和 'i' 以罗马数字表示计数器值（大写和小写）。注意，字母和罗马转换要求计数器值大于零。

formatter.flush_softspace()

将上一个调用缓冲的所有挂起空白发送到 add_flowing_data() 到关联的编写器对象。这应该在直接操作编写器对象之前调用。

formatter.push_alignment(align)

将新的对齐设置推到对齐堆栈上。这可能是 AS_IS 如果不需要更改。如果对齐值与以前的设置不同，则写入程序的 new_alignment() 方法是用 排列 价值。

formatter.pop_alignment()

恢复以前的对齐方式。

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

更改编写器对象的部分或全部字体属性。未设置为的属性 AS_IS 设置为传入的值，而其他值则保持其当前设置。作者的 new_font() 方法是使用完全解析的字体规范调用的。

formatter.pop_font()

还原以前的字体。

formatter.push_margin(margin)

将左边距缩进的数目增加一个，关联逻辑标记 边缘 新的缩进。初始保证金水平为 0 . 逻辑标记的更改值必须是真值；而不是假值 AS_IS 不足以改变保证金。

formatter.pop_margin()

恢复上一页边距。

formatter.push_style(*styles)

推送任意数量的样式规范。所有样式都按顺序推到样式堆栈上。表示整个堆栈的元组，包括 AS_IS 值，传递给编写器的 new_styles() 方法。

formatter.pop_style(n=1)

流行最后一个 n 样式规范传递给 push_style() . 表示修改后的堆栈的元组，包括 AS_IS 值，传递给编写器的 new_styles() 方法。

formatter.set_spacing(spacing)

设置书写器的间距样式。

formatter.assert_line_data(flag=1)

通知格式化程序数据已在带外添加到当前段落。这应该在作者被直接操纵时使用。可选 flag 如果编写器操作在输出末尾产生硬换行符，则可以将参数设置为false。

格式化程序实现

这个模块提供了格式化程序对象的两个实现。大多数应用程序可以使用这些类中的一个，而不需要修改或子类化。

class formatter.NullFormatter(writer=None)

一个什么都不做的格式化程序。如果*writer*被省略，A NullWriter 实例已创建。没有通过调用编写器的方法 NullFormatter 实例。如果实现了一个编写器接口，则实现应该从这个类继承，但不需要继承任何实现。

class formatter.AbstractFormatter(writer)

标准格式设置工具。这个实现已经证明了对许多作者的广泛适用性，并且可以在大多数情况下直接使用。它被用来实现一个全功能的万维网浏览器。

编写器接口

创建编写器的接口依赖于正在实例化的特定编写器类。下面描述的接口是所有编写器在初始化后必须支持的必需接口。请注意，虽然大多数应用程序都可以使用 AbstractFormatter 类作为格式化程序，编写器通常必须由应用程序提供。

writer.flush()

刷新任何缓冲输出或设备控制事件。

writer.new_alignment(align)

设置对齐样式。这个 排列 值可以是任何对象，但按约定是字符串或 None 在哪里 None 指示应使用作者的“首选”对齐方式。常规的 排列 价值观是 'left' ， 'center' ， 'right' 和 'justify' .

writer.new_font(font)

设置字体样式。价值 font 将 None ，指示应使用设备的默认字体，或窗体的元组 (size, italic, bold, teletype) . 大小将是指示应使用的字体大小的字符串；特定字符串及其解释必须由应用程序定义。这个 斜体字 ， bold 和 电传打字机 值是布尔值，指定应使用哪些字体属性。

writer.new_margin(margin, level)

将页边距级别设置为整数 level 和逻辑标签 边缘 . 对逻辑标记的解释由作者自行决定；对逻辑标记值的唯一限制是，它对于 level .

writer.new_spacing(spacing)

将间距样式设置为 间距 .

writer.new_styles(styles)

设置其他样式。这个 风格 值是任意值的元组；值 AS_IS 应该被忽略。这个 风格 根据应用程序和编写器实现的要求，元组可以解释为集合，也可以解释为堆栈。

writer.send_line_break()

打断当前行。

writer.send_paragraph(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 object 作为 file 或者，如果 file 在标准输出上省略。输出是简单的字封装到指定的列数 麦克科尔 . 此类适用于回流段落序列。