33.1. formatter - 通用输出格式

自版本3.4后已弃用：由于缺少用法，格式化程序模块已被弃用。

此模块支持两个接口定义，每个接口定义具有多个实现：格式化程序接口和格式化程序接口所需的写入程序接口。

Formatter对象将格式化事件的抽象流转换为writer对象上的特定输出事件。格式化器管理若干堆栈结构，以允许改变和恢复写入器对象的各种属性；写作者不需要能够处理相对变化或任何种类的“改变”操作。可以通过格式器对象控制的特定写入器属性是水平对齐，字体和左边缘缩进。提供了一种机制，其支持也向写者提供任意的，非排他的样式设置。其他接口有助于格式化不可逆的事件，例如段落分隔。

Writer对象封装设备接口。支持抽象设备（例如文件格式）以及物理设备。所提供的实现都使用抽象设备。该接口提供了用于设置格式化器对象管理和将数据插入到输出中的属性的可用机制。

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

formatter.add_flowing_data(data)

提供应采用折叠空格格式的数据。当执行空格折叠时，也会考虑来自先前和后续调用add_flowing_data()的空格。传递给此方法的数据预期由输出设备进行字封装。注意，任何文字包装仍然必须由writer对象执行，因为需要依赖于设备和字体信息。

formatter.add_literal_data(data)

提供应该传递给写入程序的数据不变。在数据的值中，空格（包括换行符和制表符字符）被视为合法。

formatter.add_label_data(format, counter)

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

格式规范是与计数器值结合用于计算标签值的字符串。格式字符串中的每个字符都复制到标签值，其中一些字符被识别为指示对计数器值的变换。具体来说，字符'1'表示计数器值格式化器作为阿拉伯数字，字符'A'和'a'分别表示大写和小写的计数器值，并且'I'和'i'用大写和小写表示罗马数字中的计数器值。注意，字母和罗马变换要求计数器值大于零。

formatter.flush_softspace()

将从先前调用缓冲的任何未决空格发送到add_flowing_data()到关联的writer对象。这应该在任何直接操作writer对象之前调用。

formatter.push_alignment(align)

将新的对齐设置推入对齐堆栈。如果不需要更改，则可以是AS_IS。如果对齐值从先前设置改变，则使用align值调用写入程序的new_alignment()方法。

formatter.pop_alignment()

恢复上一个对齐。

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

更改writer对象的一些或所有字体属性。未设置为AS_IS的属性设置为传入的值，而其他属性保持在其当前设置。使用完全解析的字体规范调用写入程序的new_font()方法。

formatter.pop_font()

还原以前的字体。

formatter.push_margin(margin)

将左边距缩进的数量增加1，将逻辑标记边距与新缩进相关联。初始保证金水平为0。逻辑标记的更改值必须为true值；除AS_IS之外的其他值不足以更改边距。

formatter.pop_margin()

恢复上一个边距。

formatter.push_style(*styles)

推送任意数量的任意样式规格。所有样式都按顺序推入样式堆栈。表示整个堆栈的元组（包括AS_IS值）传递给写入程序的new_styles()方法。

formatter.pop_style(n=1)

弹出传递给push_style()的最后n样式规格。表示修订堆栈（包括AS_IS值）的元组将传递给写入程序的new_styles()方法。

formatter.set_spacing(spacing)

设置作者的间距样式。

formatter.assert_line_data(flag=1)

通知格式化程序数据已经在带外添加到当前段落。当直接操作写入程序时，应使用此选项。如果写入器操作在输出结尾处产生硬换行符，则可选的标志参数可以设置为false。

33.1.2. Formatter Implementations

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

class formatter.NullFormatter(writer=None)

一个不起作用的格式化程序。如果省略writer，则会创建一个NullWriter实例。没有任何方法由NullFormatter实例调用。如果实现一个写入器接口，但不需要继承任何实现，实现应该继承这个类。

class formatter.AbstractFormatter(writer)

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

33.1.3. The Writer Interface

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

writer.flush()

清除任何缓冲输出或设备控制事件。

writer.new_alignment(align)

设置对齐样式。align值可以是任何对象，但按照惯例是一个字符串或None，其中None表示作者的“首选”用过的。常规align值为'left'，'center'，'right'和'justify'。

writer.new_font(font)

设置字体样式。字体的值将为None，表示应使用设备的默认字体，或（大小， t4 > 斜体， 粗体， 电传）。大小将是一个字符串，表示应该使用的字体大小；特定字符串及其解释必须由应用程序定义。斜体，粗体和teletype值是布尔值，指定应使用哪些字体属性。

writer.new_margin(margin, level)

将边距水平设置为整数级别，将逻辑标记设置为边距。逻辑标签的解释是由作者自行决定的；对逻辑标记的值的唯一限制是它不是电平的非零值的假值。

writer.new_spacing(spacing)

将间距样式设置为间距。

writer.new_styles(styles)

设置其他样式。样式值是任意值的元组；应忽略值AS_IS。根据应用程序和写入程序实现的要求，样式元组可以解释为一个集合或一个堆栈。

writer.send_line_break()

中断当前行。

writer.send_paragraph(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)

如果可能，请将数据设置在当前左边距的左侧。数据的值不受限制；非字符串值的处理完全取决于应用程序和写入程序。此方法将只在一行的开始处调用。

33.1.4. Writer Implementations

该模块提供了作者对象接口的三个实现作为示例。大多数应用程序将需要从NullWriter类派生新的writer类。

class formatter.NullWriter

只提供接口定义的writer；没有对任何方法采取任何行动。这应该是所有不需要继承任何实现方法的作者的基类。

class formatter.AbstractWriter

一个可以用于调试格式化器的写入器，但不是很多。每个方法通过在标准输出上打印其名称和参数来简单地宣布自身。

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

将输出写入文件传入的file object上的简单写入器类，或者如果省略文件，则在标准输出上写入输出。输出只是用字包裹到由maxcol指定的列数。这个类适合回流段序列。