KBEngine 内嵌 Python 3.7 的 xml.etree.ElementTree 完全指南:解析、构建与 XPath 实战

原创2026-10-18 12:58:502,587 阅读
文章标签:游戏开发后端

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。理解了这一分工,在编写或调试资产脚本时就能正确选择解析工具。

六、结语与选型建议

综合官方文档与仓库实现,可以总结出以下工程选型建议:

  1. 一次性加载小/中体积文档:用 ET.parse(文件)或 ET.fromstring(字符串),返回后配合 findall/iter/XPath 查找;
  2. 超大文档且可阻塞读取:用 iterparse 增量消费 "end" 事件,避免整树驻留内存;
  3. socket 分段接收等非阻塞场景:用 XMLPullParser 配合 feed/read_events;
  4. 底层事件流控制或自定义树构建:直接使用 XMLParser + 自定义 TreeBuilder/target;
  5. 涉及命名空间:优先用 namespaces 前缀映射字典,避免在路径中拼接冗长 URI;
  6. 写回文档:记住 write 的 encoding 决定输出 str 还是 bytes,并与目标流类型保持一致;
  7. 安全红线:解析不可信数据前必须先做防实体展开等加固,切勿直接信任输入。

同时留意两个官方警示:无子元素的元素布尔值为 False(应改用 len/is None 判断)、"start" 事件时元素内容未必完整(需要完整元素请等 "end" 事件)。

登录后查看全文
kbengine