33.1. formatter — 通用输出格式 — Python 文档

33.1. 格式化程序 — 通用输出格式

3.4 版本后已弃用： 由于缺乏使用，格式化程序模块已弃用。

---

该模块支持两个接口定义，每个接口定义有多种实现：formatter接口和formatter接口所需的writer接口。

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

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

33.1.1. 格式化程序接口

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

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

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)

提供应该不变地传递给作者的数据。 空格，包括换行符和制表符，在 data 的值中被认为是合法的。

formatter.add_label_data(format, counter)

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

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

formatter.flush_softspace()

将先前调用 add_flowing_data() 中缓冲的任何待处理空白发送到关联的编写器对象。 这应该在对 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)

将左边距缩进的数量增加一，将逻辑标签 margin 与新的缩进相关联。 初始保证金水平为 0。 逻辑标签的改变值必须是真值； 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)

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

33.1.2. 格式化程序实现

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

class formatter.NullFormatter(writer=None)

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

class formatter.AbstractFormatter(writer)

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

33.1.3. 编写器界面

创建编写器的接口取决于正在实例化的特定编写器类。 下面描述的接口是所有编写者在初始化后必须支持的必需接口。 请注意，虽然大多数应用程序可以使用 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)

将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的值不受限制； 非字符串值的处理完全取决于应用程序和编写器。 这个方法只会在一行的开头被调用。

33.1.4. 编写器实现

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

class formatter.NullWriter

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

class formatter.AbstractWriter

可用于调试格式化程序的编写器，但仅此而已。 每个方法都通过在标准输出上打印其名称和参数来简单地宣布自己。

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

简单的编写器类，它在作为 file 传入的 file object 上写入输出，或者，如果 file 被省略，则在标准输出上。 输出简单地换行到 maxcol 指定的列数。 此类适用于重排一系列段落。