KBEngine 内嵌 Python 3.7 的 xml.etree.ElementTree 完全指南:解析、构建与 XPath 实战
KBEngine 内嵌 Python 3.7 的 xml.etree.ElementTree 完全指南:解析、构建与 XPath 实战
本文以 KBEngine 仓库内嵌 Python 3.7 标准库自带的 xml.etree.elementtree.rst 官方文档为主体,完整覆盖 ElementTree 的树模型、四种解析方式(parse / fromstring / iterparse / XMLPullParser)、元素查找、文档修改与构建、命名空间处理、XPath 语法以及全部 API 参考,并结合仓库内 ElementTree.py 实现源码与 test_xml_etree.py 测试佐证原理。读完你可以在 KBEngine 的 Python 资产脚本、工具脚本中熟练读写 XML 配置与数据文件,并理解其底层实现机制。
一、模块概述:一棵树、两类对象
XML 本质上是层级化(hierarchical)的数据格式,最自然的表示方式就是树。xml.etree.ElementTree(下文简称 ET)用两个类承担这一职责:
ElementTree:代表整个 XML 文档的树。与整篇文档的交互(读写文件)通常在ElementTree层级完成;Element:代表树中的单个节点。与单个元素及其子元素的交互在Element层级完成。
在仓库内嵌的 Python 3.7 实现中,模块的公开符号在 ElementTree.py 的 __all__ 里完整列出,包括 Element、ElementTree、Comment、dump、fromstring、fromstringlist、iselement、iterparse、parse、ParseError、PI、ProcessingInstruction、QName、SubElement、tostring、tostringlist、TreeBuilder、VERSION、XML、XMLID、XMLParser、XMLPullParser、register_namespace,其纯 Python 实现版本标识为 VERSION = "1.3.0"(见 ElementTree.py)。
1.1 版本行为变化(3.3 起)
官方文档明确:自 Python 3.3 起,只要环境中存在 C 加速实现(_elementtree),模块就会自动使用快速实现;同时 xml.etree.cElementTree 模块被标记为已弃用。本仓库中 C 加速实现位于 kbe/src/lib/python/Modules/_elementtree.c,而 cElementTree.py 仅作为兼容层存在。测试文件 test_xml_etree.py 的头部注释说明了设计意图:同一套测试分别以 test_xml_etree(纯 Python 实现)与 test_xml_etree_c(C 加速实现)运行,以保证两种实现的行为完全一致。
1.2 安全警告(务必先读)
模块对恶意构造的数据不安全。如果需要解析不可信或未认证的数据,必须采用防御性手段(如限制实体展开、禁止 DTD 外部实体加载等)后再交给本模块处理。这是官方文档开篇的明确警告,在实际业务接入外部数据时不可忽略。
二、入门教程:从解析到构建的完整链路
本节沿用官方教程的 country_data.xml 样例数据:
<?xml version="1.0"?>
<data>
<country name="Liechtenstein">
<rank>1</rank>
<year>2008</year>
<gdppc>141100</gdppc>
<neighbor name="Austria" direction="E"/>
<neighbor name="Switzerland" direction="W"/>
</country>
<country name="Singapore">
<rank>4</rank>
<year>2011</year>
<gdppc>59900</gdppc>
<neighbor name="Malaysia" direction="N"/>
</country>
<country name="Panama">
<rank>68</rank>
<year>2011</year>
<gdppc>13600</gdppc>
<neighbor name="Costa Rica" direction="W"/>
<neighbor name="Colombia" direction="E"/>
</country>
</data>
2.1 解析 XML:文件与字符串两条路径
从文件读取:
import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml') # 返回 ElementTree 对象
root = tree.getroot() # 取根 Element
直接从字符串解析:
root = ET.fromstring(country_data_as_string) # 返回根 Element
关键差异:fromstring 直接从字符串解析出根 Element;而 parse 返回的是 ElementTree 对象,需再经 getroot() 拿到根元素。其余解析函数可能创建 ElementTree,使用时务必查阅文档确认返回类型。
解析成功后,root 作为 Element 拥有 tag(元素名)和 attrib(属性字典):
>>> root.tag
'data'
>>> root.attrib
{}
对根元素可直接迭代其子节点:
>>> for child in root:
... print(child.tag, child.attrib)
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}
子节点层层嵌套,可通过下标索引逐层访问:
>>> root[0][1].text
'2008'
解析过滤行为(官方说明):并非输入 XML 中所有内容都会变成树中的元素。当前实现会跳过 XML 注释(comments)、处理指令(processing instructions)和文档类型声明(doctype)。但通过本模块 API 手工构建的树可以包含注释与处理指令,并会在输出 XML 时被序列化出来。若要获取文档类型声明,可以向 XMLParser 构造器传入自定义的 TreeBuilder 实例。
2.2 增量解析:非阻塞 Pull API 与 iterparse
模块内大多数解析函数要求一次性读完整篇文档后才返回结果。虽然可以用 XMLParser 逐段 feed 数据,但那是把事件回调"推"到 target 对象上的 Push API,层级太低、用起来不便。真正适合增量场景的是两个工具:
XMLPullParser(非阻塞,推荐用于 socket / 增量存储读取场景):
>>> parser = ET.XMLPullParser(['start', 'end'])
>>> parser.feed('<mytag>sometext')
>>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> parser.feed(' more text</mytag>')
>>> for event, elem in parser.read_events():
... print(event)
... print(elem.tag, 'text=', elem.text)
...
end
mytag text= sometext more text
其典型使用场景正是非阻塞式应用:XML 数据从 socket 分段到达,或从存储设备增量读取,此时阻塞式读取不可接受。
iterparse(阻塞但增量,适合大文件):如果不介意阻塞读取、只希望不必把整篇大文档驻留内存,可使用 iterparse。它边解析边报告 "start"、"end"、"start-ns"、"end-ns" 事件(缺省仅报告 "end"),返回 (event, elem) 对的迭代器。
使用注意(官方文档明确):无论 XMLPullParser 还是 iterparse,当发出 "start" 事件时,只保证已看到开始标签的 > 字符——此时属性已定义,但 text / tail 内容及子元素尚未确定;若需要完整填充的元素,应改用 "end" 事件。
2.3 查找感兴趣的元素:iter / findall / find / get
Element 提供递归遍历整棵子树的迭代方法 iter:
>>> for neighbor in root.iter('neighbor'):
... print(neighbor.attrib)
...
{'name': 'Austria', 'direction': 'E'}
{'name': 'Switzerland', 'direction': 'W'}
{'name': 'Malaysia', 'direction': 'N'}
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}
findall 只查找当前元素的直接子元素中匹配指定标签的元素;find 查找第一个匹配子元素;text 访问元素文本;get 访问元素属性:
>>> for country in root.findall('country'):
... rank = country.find('rank').text
... name = country.get('name')
... print(name, rank)
...
Liechtenstein 1
Singapore 4
Panama 68
更精细的元素筛选可以使用 XPath 支持 一节中的路径表达式。
2.4 修改 XML 文件:改值、加属性、删节点、写回
ElementTree.write 是官方推荐的写出方式。Element 对象创建后可直接修改其字段(如 text)、用 set 增改属性、用 append 增加子节点。以下示例把所有国家的 rank 加 1,并给 rank 元素加 updated 属性:
>>> for rank in root.iter('rank'):
... new_rank = int(rank.text) + 1
... rank.text = str(new_rank)
... rank.set('updated', 'yes')
...
>>> tree.write('output.xml')
修改后的 XML:
<?xml version="1.0"?>
<data>
<country name="Liechtenstein">
<rank updated="yes">2</rank>
<year>2008</year>
<gdppc>141100</gdppc>
<neighbor name="Austria" direction="E"/>
<neighbor name="Switzerland" direction="W"/>
</country>
<country name="Singapore">
<rank updated="yes">5</rank>
<year>2011</year>
<gdppc>59900</gdppc>
<neighbor name="Malaysia" direction="N"/>
</country>
<country name="Panama">
<rank updated="yes">69</rank>
<year>2011</year>
<gdppc>13600</gdppc>
<neighbor name="Costa Rica" direction="W"/>
<neighbor name="Colombia" direction="E"/>
</country>
</data>
用 Element.remove 删除节点。例如删除所有 rank 大于 50 的国家:
>>> for country in root.findall('country'):
... rank = int(country.find('rank').text)
... if rank > 50:
... root.remove(country)
...
>>> tree.write('output.xml')
删除后的 XML:
<?xml version="1.0"?>
<data>
<country name="Liechtenstein">
<rank updated="yes">2</rank>
<year>2008</year>
<gdppc>141100</gdppc>
<neighbor name="Austria" direction="E"/>
<neighbor name="Switzerland" direction="W"/>
</country>
<country name="Singapore">
<rank updated="yes">5</rank>
<year>2011</year>
<gdppc>59900</gdppc>
<neighbor name="Malaysia" direction="N"/>
</country>
</data>
2.5 构建 XML 文档:SubElement 与 dump
SubElement 工厂函数可在给定元素下便捷创建子元素,dump 用于调试输出(仅建议调试时使用,输出格式随实现而定,当前版本输出为普通 XML):
>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>
2.6 解析带命名空间的 XML
若 XML 输入包含命名空间,prefix:sometag 形式的前缀标签会被展开为 {uri}sometag(前缀替换为完整 URI);若存在默认命名空间,则该 URI 会前置到所有无前缀标签上。官方示例同时使用了一个带前缀 fictional 的命名空间与一个默认命名空间:
<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
xmlns="http://people.example.com">
<actor>
<name>John Cleese</name>
<fictional:character>Lancelot</fictional:character>
<fictional:character>Archie Leach</fictional:character>
</actor>
<actor>
<name>Eric Idle</name>
<fictional:character>Sir Robin</fictional:character>
<fictional:character>Gunther</fictional:character>
<fictional:character>Commander Clement</fictional:character>
</actor>
</actors>
方式一:在路径中手工写完整 URI:
root = fromstring(xml_text)
for actor in root.findall('{http://people.example.com}actor'):
name = actor.find('{http://people.example.com}name')
print(name.text)
for char in actor.findall('{http://characters.example.com}character'):
print(' |-->', char.text)
方式二(推荐):构造前缀到 URI 的映射字典,在查找函数中传入 namespaces:
ns = {'real_person': 'http://people.example.com',
'role': 'http://characters.example.com'}
for actor in root.findall('real_person:actor', ns):
name = actor.find('real_person:name', ns)
print(name.text)
for char in actor.findall('role:character', ns):
print(' |-->', char.text)
两种方式输出一致:
John Cleese
|--> Lancelot
|--> Archie Leach
Eric Idle
|--> Sir Robin
|--> Gunther
|--> Commander Clement
三、XPath 支持:语法与实践
本模块对 XPath 表达式提供有限支持:目标是支持精简语法(abbreviated syntax)的一个小子集,完整 XPath 引擎不在模块范围之内。其实现位于 ElementPath.py,内部通过正则 xpath_tokenizer_re 对路径表达式做词法切分,再交给 xpath_tokenizer 与后续的选择引擎处理——这就是为什么支持 .//、..、[@attrib]、[position] 等子集语法的底层基础。
3.1 官方示例
以下均基于前述 countrydata 文档:
import xml.etree.ElementTree as ET
root = ET.fromstring(countrydata)
# 顶层元素
root.findall(".")
# 顶层元素下 country 子元素的 neighbor 孙元素
root.findall("./country/neighbor")
# 具有 name='Singapore' 且含有 year 子节点的节点
root.findall(".//year/..[@name='Singapore']")
# name='Singapore' 节点下的 year 子节点
root.findall(".//*[@name='Singapore']/year")
# 是其父节点第二个子节点的所有 neighbor 节点
root.findall(".//neighbor[2]")
3.2 支持的 XPath 语法速查表
| 语法 | 含义 |
|---|---|
tag |
选择所有指定标签的子元素。如 spam 选择所有名为 spam 的子元素;spam/egg 选择所有 spam 子元素下名为 egg 的孙元素 |
* |
选择所有子元素。如 */egg 选择所有名为 egg 的孙元素 |
. |
选择当前节点。主要用于路径开头,表示这是一个相对路径 |
// |
选择当前元素之下所有层级的子元素。如 .//egg 选择整棵树中所有 egg 元素 |
.. |
选择父元素。若路径试图到达起始元素(调用 find 的元素)的祖先,则返回 None |
[@attrib] |
选择所有具有指定属性的元素 |
[@attrib='value'] |
选择指定属性等于指定值的元素(值中不能含引号) |
[tag] |
选择所有含名为 tag 的直接子元素的元素(仅支持直接子元素) |
[.='text'] |
选择完整文本内容(含后代文本)等于给定 text 的元素(Python 3.7 新增) |
[tag='text'] |
选择具有名为 tag 的子元素、且该子元素完整文本内容(含后代)等于给定 text 的元素 |
[position] |
选择位于给定位置的元素。位置可为整数(1 表示第一个)、表达式 last()(最后一个),或相对最后一个位置(如 last()-1) |
谓词规则:方括号中的谓词(predicate)必须跟在标签名、星号或另一个谓词之后;position 谓词必须以标签名开头。
四、API 参考:函数、对象与异常
以下内容为官方 Reference 全量整理,并补充实现层面的关键说明。
4.1 模块级函数
| 函数 | 说明 |
|---|---|
Comment(text=None) |
注释元素工厂。创建的特殊元素会被标准序列化器输出为 XML 注释。text 可为字节串或 Unicode 字符串,返回注释元素实例。注意 XMLParser 解析时会跳过输入中的注释;ElementTree 中只会有通过 Element 方法手工插入的注释节点 |
dump(elem) |
将元素树或元素结构写入 sys.stdout,仅用于调试。输出格式取决于实现,当前版本按普通 XML 写出。elem 为元素树或单个元素 |
fromstring(text, parser=None) |
从字符串常量解析 XML 片段,与 XML 相同。text 为含 XML 数据的字符串,parser 为可选解析器实例(缺省用标准 XMLParser),返回 Element 实例 |
fromstringlist(sequence, parser=None) |
从字符串片段序列解析 XML 文档(3.2 新增)。sequence 为含 XML 片段的可迭代对象,返回 Element 实例 |
iselement(element) |
判断对象是否为合法元素对象,是则返回真值。实现见 ElementTree.py:本质是检查对象是否具有 tag 属性 |
iterparse(source, events=None, parser=None) |
增量解析 XML 为元素树并报告事件。source 为文件名或文件对象;events 支持 "start"、"end"、"start-ns"、"end-ns",缺省仅 "end";parser 必须是 XMLParser 子类且只能使用默认 TreeBuilder 作为 target。返回 (event, elem) 对的迭代器。它在构建树时仍对 source 做阻塞读,不适合非阻塞场景;parser 参数自 3.4 起弃用 |
parse(source, parser=None) |
将 XML 片段解析为元素树。source 为文件名或文件对象,返回 ElementTree 实例 |
ProcessingInstruction(target, text=None) |
PI 元素工厂。创建的元素会被序列化为 XML 处理指令。target 为 PI 目标字符串,text 为 PI 内容。解析器同样会跳过输入中的处理指令 |
register_namespace(prefix, uri) |
注册命名空间前缀(3.2 新增)。注册表是全局的,会移除给定前缀或 URI 的既有映射。序列化时该命名空间下的标签与属性会尽量使用该前缀 |
SubElement(parent, tag, attrib={}, **extra) |
子元素工厂:创建元素实例并追加到已有元素。元素名、属性名、属性值可为字节串或 Unicode 字符串。attrib 为可选属性字典,extra 为关键字形式的附加属性,返回元素实例 |
tostring(element, encoding="us-ascii", method="xml", *, short_empty_elements=True) |
生成含全部子元素的 XML 字符串。encoding 默认 US-ASCII,用 encoding="unicode" 生成 Unicode 字符串(否则返回字节串);method 为 "xml"、"html" 或 "text";short_empty_elements 自 3.4 起提供 |
tostringlist(element, encoding="us-ascii", method="xml", *, short_empty_elements=True) |
同 tostring,但返回字符串列表(3.2 新增,short_empty_elements 3.4 新增)。不保证元素顺序,但恒有 b"".join(tostringlist(element)) == tostring(element) |
XML(text, parser=None) |
从字符串常量解析 XML 片段,可用于在 Python 代码中内嵌 "XML 字面量",返回 Element 实例 |
XMLID(text, parser=None) |
从字符串解析 XML,并额外返回元素 id 到元素的映射字典,返回 (Element, dict) 元组 |
4.2 Element 对象
Element(tag, attrib={}, **extra) 是 Element 接口的参考实现。实现细节见 ElementTree.py:构造时校验 attrib 必须是 dict、复制属性字典、合并 extra 关键字参数、初始化空子元素列表 _children。
核心属性:
tag:标识元素类型的字符串(元素类型/名称);text/tail:存放与元素关联的附加数据。若元素由 XML 文件解析而来,text存放开始标签与第一个子元素或结束标签之间的文本(无则为None);tail存放结束标签与下一个标签之间的文本(无则为None)。以<a><b>1<c>2<d/>3</c></b>4</a>为例:a的 text 与 tail 均为None;b的 text 为"1"、tail 为"4";c的 text 为"2"、tail 为None;d的 text 为None、tail 为"3"。收集元素内部文本可用"".join(element.itertext())。应用可在这些属性中存放任意对象;attrib:元素属性字典。注意它总是真实可变 Python 字典(虽然实现可能内部使用其他表示、仅在访问时构造),因此尽量使用下方字典风格方法。
字典风格方法:clear()(重置元素:删除全部子元素、清空属性、text/tail 置 None)、get(key, default=None)(取属性,缺省返回 default)、items()(返回 (name, value) 序列,顺序任意)、keys()(返回属性名列表,顺序任意)、set(key, value)(设置属性)。
子元素操作方法:
append(subelement):追加到子元素列表末尾;非Element抛TypeError;extend(subelements):批量追加序列中的元素(3.2 新增);find(match, namespaces=None):查找第一个匹配子元素(支持标签名或路径),未找到返回None;findall(match, namespaces=None):按文档顺序返回所有匹配子元素的列表;findtext(match, default=None, namespaces=None):返回第一个匹配子元素的文本,未找到返回default(匹配到但无文本返回空串);getchildren()/getiterator(tag=None):3.2 起弃用,分别改用list(elem)(或迭代)与iter;insert(index, subelement):在指定位置插入子元素;iter(tag=None):以当前元素为根创建树的迭代器,按文档(深度优先)顺序遍历自身及所有后代;tag非None/'*'时仅返回匹配元素(3.2 新增)。迭代过程中修改树结构,结果未定义;iterfind(match, namespaces=None):按文档顺序返回所有匹配元素的迭代器(3.2 新增);itertext():文本迭代器,按文档顺序返回所有内部文本(3.2 新增);makeelement(tag, attrib):创建同类型新元素。官方明确建议不要调用此方法,改用SubElement工厂函数;remove(subelement):删除子元素。与 find 系列不同,它按实例身份而非标签值或内容比较。
Element 还支持序列方法:__delitem__、__getitem__、__setitem__、__len__。
重要陷阱(官方明确警示):没有子元素的 Element 在布尔测试中为 False,该行为未来版本会改变,应改用 len(elem) 或 elem is None 判断:
element = root.find('foo')
if not element: # 小心!
print("element not found, or element has no subelements")
if element is None:
print("element not found")
4.3 ElementTree 对象
ElementTree(element=None, file=None) 包装整棵元素层级,并额外支持标准 XML 的序列化与反序列化。element 为根元素;若给定 file,则以该 XML 文件内容初始化树。
_setroot(element):替换根元素(丢弃当前全部内容,谨慎使用);find/findall/findtext:与Element同名方法相同,但从树的根开始查找;getiterator(tag=None):3.2 起弃用,改用iter;getroot():返回树的根元素;iter(tag=None):为根元素创建并返回树迭代器,按文档顺序遍历整棵树;iterfind(match, namespaces=None):同Element.iterfind,从根开始(3.2 新增);parse(source, parser=None):将外部 XML 片段加载进该元素树,返回片段根元素;write(file, encoding="us-ascii", xml_declaration=None, default_namespace=None, method="xml", *, short_empty_elements=True):将元素树以 XML 写入文件(文件名或已打开的写文件对象)。encoding默认 US-ASCII;xml_declaration控制是否输出 XML 声明:False永不、True总是、None仅当编码非 US-ASCII/UTF-8/Unicode 时(默认None);default_namespace设置默认 XML 命名空间(对应 "xmlns");method为"xml"/"html"/"text";关键字参数short_empty_elements(3.4 新增)控制无内容元素的写法:True(默认)输出自闭合标签,False输出成对的开始/结束标签。输出类型由encoding决定:encoding="unicode"输出str,否则输出bytes——注意与已打开文件对象的流类型匹配,不要把字符串写入二进制流或反之。
官方给出的 XHTML 实操示例(给第一段中的所有链接加 target="blank" 属性):
>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p") # 查找 body 中第一个 p 标签
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a")) # 返回所有 a 链接
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links: # 遍历所有链接
... i.attrib["target"] = "blank"
>>> tree.write("output.xhtml")
4.4 QName 对象
QName(text_or_uri, tag=None):QName 包装器,用于包装 QName 属性值以获得正确的输出命名空间处理。text_or_uri 为 {uri}local 形式的字符串;若给出 tag,则第一个参数被解释为 URI、第二个为本地名。QName 实例是不透明的。
4.5 TreeBuilder 对象
TreeBuilder(element_factory=None):通用元素结构构建器,把 start、data、end 方法调用序列转换为良构元素结构。可配合自定义 XML 解析器或解析其他类 XML 格式。element_factory 若给定,必须是接受两个位置参数(tag 与属性 dict)、返回新元素实例的可调用对象。
close():冲刷构建器缓冲区,返回顶层文档元素;data(data):向当前元素追加文本(字节串或 Unicode 字符串);end(tag):关闭当前元素,返回已关闭的元素;start(tag, attrs):打开新元素,返回打开的元素。
自定义 TreeBuilder 还可提供 doctype(name, pubid, system) 方法(3.2 新增)处理文档类型声明——默认 TreeBuilder 类没有此方法。这也正是第一节提到的"通过自定义 TreeBuilder 获取文档类型声明"的入口。
4.6 XMLParser 对象
XMLParser(html=0, target=None, encoding=None):模块的底层构件,基于 xml.parsers.expat 做高效的基于事件的 XML 解析。可用 feed 增量喂入数据,解析事件通过回调 target 对象的方法转为 Push API。target 缺省为标准 TreeBuilder;html 参数仅为历史兼容,已弃用(3.4);encoding 若给定,覆盖 XML 文件声明的编码。
close():结束喂入数据,返回构造时传入 target 的close()方法结果(默认为顶层文档元素);doctype(name, pubid, system):3.2 起弃用,改在自定义TreeBuilder上定义doctype方法;feed(data):向解析器喂入编码数据。
feed 对每个开始标签调用 target 的 start(tag, attrs_dict),对每个结束标签调用 end(tag),文本由 data(data) 处理,close 调用 target 的 close()。因此 XMLParser 不只用于构建树——官方给出用它计算 XML 文件最大嵌套深度的示例:
>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth: # 解析器的 target 对象
... maxDepth = 0
... depth = 0
... def start(self, tag, attrib): # 每个开始标签调用
... self.depth += 1
... if self.depth > self.maxDepth:
... self.maxDepth = self.depth
... def end(self, tag): # 每个结束标签调用
... self.depth -= 1
... def data(self, data):
... pass # 无需处理文本
... def close(self): # 所有数据解析完毕后调用
... return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
... <b>
... </b>
... <b>
... <c>
... <d>
... </d>
... </c>
... </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4
4.7 XMLPullParser 对象
XMLPullParser(events=None):适用于非阻塞应用的 Pull 解析器(3.4 新增)。输入侧 API 与 XMLParser 类似,但不再把调用推给回调 target,而是收集内部解析事件列表供用户读取。events 支持 "start"、"end"、"start-ns"、"end-ns",缺省仅报告 "end"。
feed(data):喂入字节数据;close():通知解析器数据流终止。与XMLParser.close不同,总是返回None;关闭时尚未取走的任何事件仍可用read_events读取;read_events():返回已解析事件的迭代器,产出(event, elem)对。之前调用中已取走的事件不会再次产出;事件仅在从迭代器取出时才从内部队列消费,因此多个并行迭代器的读取结果不可预期。
同样注意 "start" 事件时 text/tail/子元素未定的限制(见 2.2 节)。
4.8 异常:ParseError
ParseError 是各解析方法解析失败时抛出的异常,其字符串表示包含用户友好的错误信息,此外有两个属性:
code:expat 解析器返回的数字错误码(错误码列表见xml.parsers.expat文档);position:(line, column)元组,指明错误发生位置。
实现上它继承自 SyntaxError,见 ElementTree.py。
五、KBEngine 仓库中的实际应用场景
xml.etree.ElementTree 是 Python 3.7 标准库的一部分,本仓库在 kbe/src/lib/python 下完整内嵌了该运行时(含 ElementTree.py、C 加速模块 Modules/_elementtree.c、XPath 实现 ElementPath.py 及兼容层 cElementTree.py)。因此,凡运行于该 Python 环境中的引擎工具脚本,均可直接 import xml.etree.ElementTree as ET 使用全部上述能力。
仓库内真实的接入示例位于 kbe/tools/server/install/installer.py,其第 9 行即 from xml.etree import ElementTree as ET——安装器脚本通过该模块解析安装过程中涉及的 XML 数据。
值得对比的工程实践:KBEngine 服务器端的 XML 配置(如 kbe_defaults.xml、各 app 的配置文件)在 C++ 侧由 TinyXML 负责解析,可参考 kbe/src/lib/server/serverconfig.cpp 中 TiXmlNode、enterNode、getRootNode、getValStr、getValInt 等调用。也就是说:引擎核心(C++)配置走 TinyXML,Python 脚本侧的 XML 处理走 ElementTree。理解了这一分工,在编写或调试资产脚本时就能正确选择解析工具。
六、结语与选型建议
综合官方文档与仓库实现,可以总结出以下工程选型建议:
- 一次性加载小/中体积文档:用
ET.parse(文件)或ET.fromstring(字符串),返回后配合findall/iter/XPath 查找; - 超大文档且可阻塞读取:用
iterparse增量消费"end"事件,避免整树驻留内存; - socket 分段接收等非阻塞场景:用
XMLPullParser配合feed/read_events; - 底层事件流控制或自定义树构建:直接使用
XMLParser+ 自定义TreeBuilder/target; - 涉及命名空间:优先用
namespaces前缀映射字典,避免在路径中拼接冗长 URI; - 写回文档:记住
write的encoding决定输出str还是bytes,并与目标流类型保持一致; - 安全红线:解析不可信数据前必须先做防实体展开等加固,切勿直接信任输入。
同时留意两个官方警示:无子元素的元素布尔值为 False(应改用 len/is None 判断)、"start" 事件时元素内容未必完整(需要完整元素请等 "end" 事件)。