xml.dom.pulldom --- 对构建部分 DOM 树的支持

源代码: Lib/xml/dom/pulldom.py

---

xml.dom.pulldom 模块提供了一个“拉取解析器”，它能在必要时被用于产生文件的可访问 DOM 的片段。 其基本概念包括从输入的 XML 流拉取“事件”并处理它们。 与同样地同时应用了事件驱动处理模型加回调函数的 SAX 不同，拉取解析器的用户要负责显式地从流拉取事件，并循环遍历这些事件直到处理结束或者发生了错误条件。

备注

如果你需要解析不受信任或未经身份验证的数据，请参阅 XML 安全。

在 3.7.1 版本发生变更: SAX 解析器默认不再处理一般外部实体以提升在默认情况下的安全性。 要启用外部实体处理，请传入一个自定义的解析器实例:

from xml.dom.pulldom import parse
from xml.sax import make_parser
from xml.sax.handler import feature_external_ges

parser = make_parser()
parser.setFeature(feature_external_ges, True)
parse(filename, parser=parser)

示例:

from xml.dom import pulldom

doc = pulldom.parse('sales_items.xml')
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'item':
        if int(node.getAttribute('price')) > 50:
            doc.expandNode(node)
            print(node.toxml())

event 是下列常量之一，而 node 是该事件所涉及的节点。 这些节点实现了 xml.dom 接口；它们是由提供给 PullDOM 的 DOM 实现所创建的，默认情况下该实现为 xml.dom.minidom。

xml.dom.pulldom.START_DOCUMENT

xml.dom.pulldom.END_DOCUMENT

文档的起始和结束。 node 是 Document。

xml.dom.pulldom.START_ELEMENT

xml.dom.pulldom.END_ELEMENT

元素的起始和结束标记。 node 是 Element。

xml.dom.pulldom.CHARACTERS

字符数据。 node 是 Text 节点。

xml.dom.pulldom.IGNORABLE_WHITESPACE

元素内容中的空白符，见 DTD 中的声明。 node 是 Text 节点。

xml.dom.pulldom.COMMENT

注释。 node 是 Comment 节点。

xml.dom.pulldom.PROCESSING_INSTRUCTION

处理指令。 node 是 ProcessingInstruction 节点。

由于文档是被当作“展平”的事件流来处理的，文档“树”会被隐式地遍历并且无论所需元素在树中的深度如何都会被找到。 换句话说，不需要考虑层级问题，例如文档节点的递归搜索等，但是如果元素的内容很重要，则有必要保留一些上下文相关的状态（例如记住任意给定点在文档中的位置）或者使用 DOMEventStream.expandNode() 方法并切换到 DOM 相关的处理过程。

class xml.dom.pulldom.PullDOM(documentFactory=None)

xml.sax.handler.ContentHandler 的子类，它将 SAX 事件转换为拉取解析器的事件。 节点会被创建，但不会被添加到树中，除非调用了 expandNode()。 如果给出了 documentFactory，它是一个用于创建文档的 DOM 实现；默认使用 xml.dom.minidom 的实现。

class xml.dom.pulldom.SAX2DOM(documentFactory=None)

PullDOM 的子类，它还会将每个创建的节点添加到树中，从而构建出完整的文档。

xml.dom.pulldom.parse(stream_or_string, parser=None, bufsize=None)

基于给定的输入返回一个 DOMEventStream。 stream_or_string 可以是一个文件名，或是一个文件型对象。 parser 如果给出，则必须是一个 XMLReader 对象。 此函数将改变解析器的文档处理程序并激活命名空间支持；其他解析器配置（例如设置实体解析器）必须在之前已完成。

如果你将 XML 存放为字符串形式，则可以改用 parseString() 函数:

xml.dom.pulldom.parseString(string, parser=None)

返回一个代表 string 的 DOMEventStream。 string 必须是 str 实例；要解析字节，请将二进制文件对象传递给 parse()。

xml.dom.pulldom.default_bufsize

将 bufsize 形参的默认值设为 parse()。

此变量的值可在调用 parse() 之前修改并使新值生效。

DOMEventStream 对象

class xml.dom.pulldom.DOMEventStream(stream, parser, bufsize)

针对由 XMLReader 解析器 parser 从文件对象 stream 中读取的数据产生事件。 数据每次读取 bufsize 个字节，对于文本流则读取 bufsize 个字符。

在 3.11 版本发生变更: 对 __getitem__() 方法的支持已被移除。

getEvent()

返回下一个 (event, node) 元组，或者在文档末尾返回 None。 关于事件及对应的节点请参见上文。 当前节点不包含有关其子节点的信息，除非调用了 expandNode()。

expandNode(node)

将 node 的所有子节点扩展到 node 中。 例如:

from xml.dom import pulldom

xml = '<html><title>Foo</title> <p>Some text <div>and more</div></p> </html>'
doc = pulldom.parseString(xml)
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'p':
        # 以下语句只打印 '<p/>'
        print(node.toxml())
        doc.expandNode(node)
        # 以下语句将打印节点所有的子节点 '<p>Some text <div>and more</div></p>'
        print(node.toxml())

reset()

丢弃尚未读取的事件并准备对象以解析新文档。

clear()

释放解析器和文档。 流尚未被关闭，而对象将无法继续使用。