Skip to main content

33.1. formatter —通用输出格式

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


此模块支持两个接口定义,每个接口定义具有多个实现:formatter 接口和格式化程序接口所需的 writer 接口。

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

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

33.1.1. 格式化程序接口

创建格式化程序的接口取决于要实例化的特定格式化程序类。下面描述的接口是所有格式化器必须支持的接口,一旦初始化。

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

formatter.AS_IS

可以在字体规范中使用的值传递给下面描述的 push_font() 方法,或作为任何其他 push_property() 方法的新值。推送 AS_IS 值允许调用相应的 pop_property() 方法,而不必跟踪属性是否已更改。

为格式化程序实例对象定义了以下属性:

formatter.writer

格式化程序与之交互的写入程序实例。

formatter.end_paragraph(blanklines)

关闭任何打开的段落,并在下一段落之前至少插入 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对象。这应该在任何直接操作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。逻辑标记的更改值必须为true值;除 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。

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) 形式的元组。大小将是一个字符串,表示应使用的字体大小;特定字符串及其解释必须由应用程序定义。 italicboldteletype 值是布尔值,指定应使用哪些字体属性。

writer.new_margin(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. Writer实现

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

class formatter.NullWriter

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

class formatter.AbstractWriter

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

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

简单的写入器类,将输出写入以 file 传递的 file object,或者如果省略 file,则在标准输出上写入。输出是简单的字包装到 maxcol 指定的列数。这个类适合回流段序列。