19.15. xml.parsers.expat —使用 Expat 的快速 XML 解析

Warning

pyexpat模块对于防止恶意构建的数据并不安全。如果您需要解析不可信或未经身份验证的数据，请参见XML vulnerabilities。

2.0 版中的新Function。

xml.parsers.expat模块是 Expat 非验证 XML 解析器的 Python 接口。该模块提供了一个 extensionsxmlparser，它表示 XML 解析器的当前状态。创建xmlparser对象后，可以将对象的各种属性设置为处理函数。然后将 XML 文档 Importing 解析器时，将为 XML 文档中的字符数据和标记调用处理程序函数。

该模块使用pyexpat模块提供对 Expat 解析器的访问。不建议直接使用pyexpat模块。

此模块提供一个异常和一个类型对象：

exception xml.parsers.expat. ExpatError
- Expat 报告错误时引发的异常。有关解释 Expat 错误的更多信息，请参见ExpatError Exceptions部分。
exception xml.parsers.expat. error
- ExpatError的别名。
xml.parsers.expat. XMLParserType
- ParserCreate()函数的返回值的类型。

xml.parsers.expat模块包含两个Function：

xml.parsers.expat. ErrorString(* errno *)
- 返回给定错误号* errno *的说明性字符串。
xml.parsers.expat. ParserCreate([* encoding * [，* namespace_separator *]])
- 创建并返回一个新的xmlparser对象。 * encoding (如果已指定)必须是一个命名 XML 数据使用的编码的字符串。 Expat 不支持 Python 所支持的多种编码，并且其编码范围无法扩展。它支持 UTF-8，UTF-16，ISO-8859-1(Latin1)和 ASCII。如果指定 encoding * [1]，它将覆盖文档的隐式或显式编码。

Expat 可以选择为您提供 XML 名称空间处理，方法是为* namespace_separator *提供一个值。该值必须是一个单字符字符串；如果字符串的长度非法(则将None视为与Ellipsis相同)，则将引发ValueError。启用名称空间处理后，属于名称空间的元素类型名称和属性名称将被扩展。传递给元素处理程序StartElementHandler和EndElementHandler的元素名称将是名称空间 URI，名称空间分隔符和名称的本地部分的串联。如果名称空间分隔符为零字节(chr(0))，则名称空间 URI 和本地部分将被串联而没有任何分隔符。

例如，如果将* namespace_separator *设置为空格字符(' ')，并且将分析以下文档：

<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>

StartElementHandler将为每个元素接收以下字符串：

http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2

由于pyexpat使用的Expat库中的限制，返回的xmlparser实例只能用于解析单个 XML 文档。为每个文档调用ParserCreate以提供唯一的解析器实例。

19.15.1. XMLParser 对象

xmlparser对象具有以下方法：

xmlparser. Parse(* data * [，* isfinal *])
- 解析字符串* data 的内容，调用适当的处理函数以处理解析的数据。在此方法的finally调用中， isfinal *必须为 true；它允许以片段的形式解析单个文件，而不是多个文件的提交。 * data *可以随时为空字符串。
xmlparser. ParseFile(* file *)
- 解析从对象* file *读取的 XML 数据。 * file *只需要提供read(nbytes)方法，在没有更多数据时返回空字符串。
xmlparser. SetBase(* base *)
- 设置用于解析语句中系统标识符中的相对 URI 的基础。解决相对标识符留给应用程序：此值将作为** 基础参数传递给ExternalEntityRefHandler()，NotationDeclHandler()和UnparsedEntityDeclHandler()函数。
xmlparser. GetBase ( )
- 返回一个字符串，该字符串包含先前调用SetBase()或None(如果尚未调用SetBase())而设置的基数。
xmlparser. GetInputContext ( )
- 以字符串形式返回生成当前事件的 Importing 数据。数据采用包含文本的实体的编码。在事件处理程序不活动时调用时，返回值为None。

2.1 版中的新Function。

xmlparser. ExternalEntityParserCreate(* context * [，* encoding *])
- 创建一个“子”解析器，该解析器可用于解析由父解析器解析的内容所引用的外部解析实体。 * context *参数应该是传递给ExternalEntityRefHandler()处理函数的字符串，如下所述。子解析器是使用ordered_attributes，returns_unicode和specified_attributes设置为此解析器的值创建的。
xmlparser. SetParamEntityParsing(* flag *)
- 控制参数实体(包括外部 DTD 子集)的解析。可能的* flag *值为XML_PARAM_ENTITY_PARSING_NEVER，XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE和XML_PARAM_ENTITY_PARSING_ALWAYS。如果设置标志成功，则返回 true。
xmlparser. UseForeignDTD([* flag *])
- 使用* flag *(默认值)的真值调用此函数将使 Expat 为所有参数调用ExternalEntityRefHandler和None，以允许加载备用 DTD。如果文档不包含文档类型语句，则仍将调用ExternalEntityRefHandler，但不会调用StartDoctypeDeclHandler和EndDoctypeDeclHandler。

为* flag *传递错误的值将取消先前传递真实值的调用，否则无效。

该方法只能在调用Parse()或ParseFile()方法之前调用；在调用其中任何一个之后调用它会导致ExpatError在code属性设置为errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING的情况下引发。

2.3 版的新Function。

xmlparser个对象具有以下属性：

xmlparser. buffer_size
- buffer_text为 true 时使用的缓冲区大小。可以pass为该属性分配新的整数值来设置新的缓冲区大小。更改大小后，缓冲区将被刷新。

2.3 版的新Function。

在 2.6 版中更改：现在可以更改缓冲区大小。

xmlparser. buffer_text
- 将此属性设置为 true 会导致xmlparser对象缓冲 Expat 返回的文本内容，以避免在可能的情况下多次调用CharacterDataHandler()回调。由于 Expat 通常会在每行末尾将字符数据分成多个块，因此可以大大提高性能。默认情况下，此属性为 false，可以随时更改。

2.3 版的新Function。

xmlparser. buffer_used
- 如果启用了buffer_text，则缓冲区中存储的字节数。这些字节代表 UTF-8 编码的文本。当buffer_text为 false 时，此属性没有有意义的解释。

2.3 版的新Function。

xmlparser. ordered_attributes
- 将此属性设置为非零整数会导致将属性报告为列表而不是字典。属性以文档文本中找到的 Sequences 显示。对于每个属性，都会显示两个列表条目：属性名称和属性值。 (此模块的较旧版本也使用此格式.)默认情况下，此属性为 false；否则为 false。它可以随时更改。

2.1 版中的新Function。

xmlparser. returns_unicode
- 如果将此属性设置为非零整数，则处理函数将传递 Unicode 字符串。如果returns_unicode是False，则包含 UTF-8 编码数据的 8 位字符串将传递给处理程序。如果 Python 是使用 Unicode 支持构建的，则默认为True。

在版本 1.6 中更改：可以随时更改以影响结果类型。

xmlparser. specified_attributes
- 如果设置为非零整数，则解析器将仅报告在文档实例中指定的那些属性，而不报告从属性语句派生的那些属性。设置此设置的应用程序必须格外小心，以根据需要使用语句中提供的哪些附加信息，以符合 XML 处理器行为的标准。默认情况下，此属性为 false；否则为 false。它可以随时更改。

2.1 版中的新Function。

以下属性包含与xmlparser对象遇到的最新错误相关的值，并且仅在对Parse()或ParseFile()的调用引发xml.parsers.expat.ExpatError异常后才具有正确的值。

xmlparser. ErrorByteIndex
- 发生错误的字节索引。
xmlparser. ErrorCode
- 指定问题的数字代码。该值可以传递给ErrorString()函数，或者与errors对象中定义的常量之一进行比较。
xmlparser. ErrorColumnNumber
- 发生错误的列号。
xmlparser. ErrorLineNumber
- 发生错误的行号。

以下属性包含与xmlparser对象中的当前解析位置有关的值。在报告解析事件的回调过程中，它们指示生成事件的字符序列中第一个字符的位置。在回调之外调用时，指示的位置将刚好在上一个解析事件之后(无论是否有关联的回调)。

2.4 版的新Function。

xmlparser. CurrentByteIndex
- 解析器 Importing 中的当前字节索引。
xmlparser. CurrentColumnNumber
- 解析器 Importing 中的当前列号。
xmlparser. CurrentLineNumber
- 解析器 Importing 中的当前行号。

这是可以设置的处理程序列表。要在xmlparser对象* o *上设置处理程序，请使用o.handlername = func。 * handlername 必须从以下列表中获取，并且 func *必须是接受正确数目的参数的可调用对象。除非另有说明，否则参数均为字符串。

xmlparser. XmlDeclHandler(版本，编码，独立)
- 解析 XML 语句时调用。 XML 语句是适用的 XML 建议版本的(可选)语句，文档文本的编码以及可选的“独立”语句。 * version 和 encoding 将是returns_unicode属性所指定类型的字符串，如果文档被语句为独立文档，则 standalone *将为1；如果文档被语句为非独立文档，则为0；如果 standalone 子句是-1Ellipsis。仅适用于 Expat 1.95.0 或更高版本。

2.1 版中的新Function。

xmlparser. StartDoctypeDeclHandler(* doctypeName ， systemId ， publicId ， has_internal_subset *)
- 当 Expat 开始解析文档类型语句(<!DOCTYPE ...)时调用。 * doctypeName 的提供与提供的完全相同。如果指定了 systemId 和 publicId 参数，则提供系统和公共标识符；如果Ellipsis，则提供None。如果文档包含内部文档语句子集，则 has_internal_subset *将为 true。这需要 Expat 1.2 版或更高版本。
xmlparser. EndDoctypeDeclHandler ( )
- 当 Expat 完成文档类型语句的解析时调用。这需要 Expat 1.2 版或更高版本。
xmlparser. ElementDeclHandler(* name ， model *)
- 为每个元素类型语句调用一次。 * name 是元素类型的名称，而 model *是内容模型的表示。
xmlparser. AttlistDeclHandler(* elname ， attname ， type ， default ， required *)
- 为元素类型的每个语句的属性调用。如果属性列表语句语句了三个属性，则此处理程序将被调用三次，每个属性一次。 * elname 是语句适用的元素的名称， attname 是语句的属性的名称。属性类型是作为 type 传递的字符串；可能的值为'CDATA'，'ID'，'IDREF'，… default 给出当文档实例未指定属性时使用的属性的默认值；如果没有默认值(#IMPLIED值)，则为None。如果要求在文档实例中提供该属性，则 required *为 true。这需要 Expat 1.95.0 或更高版本。
xmlparser. StartElementHandler(* name ， attributes *)
- 要求每个元素的开始。 * name 是包含元素名称的字符串，而 attributes *是将属性名称 Map 为其值的字典。
xmlparser. EndElementHandler(* name *)
- 要求每个元素的结尾。
xmlparser. ProcessingInstructionHandler(* target ， data *)
- 调用每个处理指令。
xmlparser. CharacterDataHandler(* data *)
- 要求 Importing 字符数据。正常字符数据，CDATA 标记的内容和可忽略的空白将被调用。必须区分这些情况的应用程序可以使用StartCdataSectionHandler，EndCdataSectionHandler和ElementDeclHandler回调来收集所需的信息。
xmlparser. UnparsedEntityDeclHandler(* entityName ， base ， systemId ， publicId ， notationName *)
- 调用未解析的(NDATA)实体语句。仅适用于 Expat 库的 1.2 版。要获取最新版本，请改用EntityDeclHandler。 (Expat 库中的基础Function已被宣布作废.)
xmlparser. EntityDeclHandler(* entityName ， is_parameter_entity ， value ， base ， systemId ， publicId ， notationName *)
- 要求所有实体语句。对于参数和内部实体，* value 将是给出实体语句内容的字符串；对于外部实体，这将是None。对于已解析的实体， notationName 参数将为None，对于未解析的实体，参数的名称将为。如果实体是参数实体，则 is_parameter_entity 将为 true；对于一般实体， is_parameter_entity *将为 false(大多数应用程序只需要与一般实体有关)。仅从 Expat 库的 1.95.0 版开始可用。

2.1 版中的新Function。

xmlparser. NotationDeclHandler(* notationName ， base ， systemId ， publicId *)
- 要求符号语句。 * notationName ， base 和 systemId 以及 publicId 是字符串(如果提供)。如果Ellipsis公共标识符，则 publicId *将为None。
xmlparser. StartNamespaceDeclHandler(前缀，* uri *)
- 当元素包含名称空间语句时调用。命名空间语句在放置语句的元素被调用StartElementHandler之前被处理。
xmlparser. EndNamespaceDeclHandler(前缀)
- 当包含命名空间语句的元素到达结束标记时调用。对于元素上的每个命名空间语句，将以与调用StartNamespaceDeclHandler的 Sequences 相反的 Sequences 调用一次，以指示每个命名空间语句的范围的开始。在元素末尾的相应EndElementHandler之后调用此处理程序。
xmlparser. CommentHandler(* data *)
- 征求意见。 * data *是 Comments 的文本，不包括开头的'<!- -'和结尾的'- ->'。
xmlparser. StartCdataSectionHandler ( )
- 在 CDATA 节的开头调用。需要此和EndCdataSectionHandler才能识别 CDATA 节的句法起点和 endpoints。
xmlparser. EndCdataSectionHandler ( )
- 在 CDATA 节的末尾调用。
xmlparser. DefaultHandler(* data *)
- 调用 XML 文档中未指定任何适用处理程序的任何字符。这意味着字符是可以报告的结构的一部分，但尚未提供处理程序。
xmlparser. DefaultHandlerExpand(* data *)
- 这与DefaultHandler()相同，但不禁止内部实体的扩展。实体引用不会传递给默认处理程序。
xmlparser. NotStandaloneHandler ( )
- 如果尚未将 XML 文档语句为独立文档，则调用此方法。当存在外部子集或对参数实体的引用，但 XML 语句在 XML 语句中未将独立语句设置为yes时，会发生这种情况。如果此处理程序返回0，则解析器将引发XML_ERROR_NOT_STANDALONE错误。如果未设置此处理程序，则解析器不会针对这种情况引发异常。
xmlparser. ExternalEntityRefHandler(* context ， base ， systemId ， publicId *)
- 要求引用外部实体。 * base 是当前基数，由上一次调用SetBase()设置。公用标识符和系统标识符 systemId 和 publicId 是字符串(如果提供)；如果未提供公共标识符，则 publicId *将为None。 * context *值是不透明的，仅应按以下说明使用。

对于要解析的外部实体，必须实现此处理程序。它负责使用ExternalEntityParserCreate(context)创建子解析器，并使用适当的回调对其进行初始化，并解析实体。该处理程序应返回一个整数；如果返回0，则解析器将引发XML_ERROR_EXTERNAL_ENTITY_HANDLING错误，否则解析将 continue。

如果未提供此处理程序，则由DefaultHandler回调(如果提供)报告外部实体。

19.15.2. ExpatError 异常

ExpatError异常具有许多有趣的属性：

ExpatError. code
- 针对特定错误的 Expat 内部错误号。这将与该模块中errors对象中定义的常量之一匹配。

2.1 版中的新Function。

ExpatError. lineno
- 检测到错误的行号。第一行编号为1。

2.1 版中的新Function。

ExpatError. offset
- 字符偏移到发生错误的行中。第一列编号为0。

2.1 版中的新Function。

19.15.3. Example

下面的程序定义了三个只输出其参数的处理程序。

import xml.parsers.expat

# 3 handler functions
def start_element(name, attrs):
    print 'Start element:', name, attrs
def end_element(name):
    print 'End element:', name
def char_data(data):
    print 'Character data:', repr(data)

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)

该程序的输出为：

Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent

19.15.4. 内容模型说明

使用嵌套 Tuples 描述内容模型。每个 Tuples 包含四个值：类型，量词，名称和子级 Tuples。子代只是附加的内容模型描述。

前两个字段的值是在xml.parsers.expat模块的model对象中定义的常量。这些常量可以分为两组：模型类型组和量词组。

模型类型组中的常量为：

xml.parsers.expat. XML_CTYPE_ANY
- 语句了由模型名称命名的元素的内容模型为ANY。
xml.parsers.expat. XML_CTYPE_CHOICE
- named 元素允许从多个选项中进行选择。用于诸如(A | B | C)之类的内容模型。
xml.parsers.expat. XML_CTYPE_EMPTY
- 语句为EMPTY的元素具有此模型类型。
xml.parsers.expat. XML_CTYPE_MIXED
xml.parsers.expat. XML_CTYPE_NAME
xml.parsers.expat. XML_CTYPE_SEQ
- 用这种模型类型表示代表一系列彼此接连的模型的模型。用于(A, B, C)之类的模型。

量词组中的常量为：

xml.parsers.expat. XML_CQUANT_NONE
- 没有给出修饰符，因此它只能出现一次，就像A一样。
xml.parsers.expat. XML_CQUANT_OPT
- 该模型是可选的：就A?而言，它可以显示一次或完全不显示。
xml.parsers.expat. XML_CQUANT_PLUS
- 该模型必须发生一次或多次(如A+)。
xml.parsers.expat. XML_CQUANT_REP
- 与A*一样，该模型必须出现 0 次或多次。

19.15.5. 扩展错误常量

xml.parsers.expat模块的errors对象中提供了以下常量。这些常量在解释发生错误时引发的ExpatError异常对象的某些属性时很有用。

errors对象具有以下属性：

xml.parsers.expat. XML_ERROR_ASYNC_ENTITY
xml.parsers.expat. XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF
- 属性值中的实体引用是指外部实体而不是内部实体。
xml.parsers.expat. XML_ERROR_BAD_CHAR_REF
- 字符引用引用了 XML 中非法的字符(例如，字符0或'')。
xml.parsers.expat. XML_ERROR_BINARY_ENTITY_REF
- 实体引用是指已使用符号语句的实体，因此无法解析。
xml.parsers.expat. XML_ERROR_DUPLICATE_ATTRIBUTE
- 在开始标记中多次使用一个属性。
xml.parsers.expat. XML_ERROR_INCORRECT_ENCODING
xml.parsers.expat. XML_ERROR_INVALID_TOKEN
- 在无法将 Importing 字节正确分配给字符时引发；例如，UTF-8Importing 流中的 NUL 字节(值0)。
xml.parsers.expat. XML_ERROR_JUNK_AFTER_DOC_ELEMENT
- 在文档元素之后出现了除空格以外的其他内容。
xml.parsers.expat. XML_ERROR_MISPLACED_XML_PI
- 在 Importing 数据的开头以外的地方找到了 XML 语句。
xml.parsers.expat. XML_ERROR_NO_ELEMENTS
- 该文档不包含任何元素(XML 要求所有文档仅包含一个顶级元素)。
xml.parsers.expat. XML_ERROR_NO_MEMORY
- Expat 无法在内部分配内存。
xml.parsers.expat. XML_ERROR_PARAM_ENTITY_REF
- 在不允许的地方找到了参数实体引用。
xml.parsers.expat. XML_ERROR_PARTIAL_CHAR
- 在 Importing 中发现不完整的字符。
xml.parsers.expat. XML_ERROR_RECURSIVE_ENTITY_REF
- 实体引用包含对同一实体的另一个引用；可能使用其他名称，也可能间接使用。
xml.parsers.expat. XML_ERROR_SYNTAX
- 遇到一些未指定的语法错误。
xml.parsers.expat. XML_ERROR_TAG_MISMATCH
- 结束标签与最里面的开始标签不匹配。
xml.parsers.expat. XML_ERROR_UNCLOSED_TOKEN
- 在流结束或遇到下一个标记之前，未关闭某些标记(例如开始标记)。
xml.parsers.expat. XML_ERROR_UNDEFINED_ENTITY
- 引用了一个未定义的实体。
xml.parsers.expat. XML_ERROR_UNKNOWN_ENCODING
- Expat 不支持文档编码。
xml.parsers.expat. XML_ERROR_UNCLOSED_CDATA_SECTION
- CDATA 标记的部分未关闭。
xml.parsers.expat. XML_ERROR_EXTERNAL_ENTITY_HANDLING
xml.parsers.expat. XML_ERROR_NOT_STANDALONE
- 解析器确定该文档虽然语句自己位于 XML 语句中，但它不是“独立的”，并且设置了NotStandaloneHandler并返回0。
xml.parsers.expat. XML_ERROR_UNEXPECTED_STATE
xml.parsers.expat. XML_ERROR_ENTITY_DECLARED_IN_PE
xml.parsers.expat. XML_ERROR_FEATURE_REQUIRES_XML_DTD
- 请求了需要编译 DTD 支持的操作，但是 Expat 配置为没有 DTD 支持。 xml.parsers.expat模块的标准内部版本绝对不应报告此情况。
xml.parsers.expat. XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING
- 解析开始后要求进行行为更改，该行为只能在解析开始之前进行更改。 (当前)仅由UseForeignDTD()引发。
xml.parsers.expat. XML_ERROR_UNBOUND_PREFIX
- 启用名称空间处理时，发现未语句的前缀。
xml.parsers.expat. XML_ERROR_UNDECLARING_PREFIX
- 该文档try删除与前缀关联的名称空间语句。
xml.parsers.expat. XML_ERROR_INCOMPLETE_PE
- 参数实体包含不完整的标记。
xml.parsers.expat. XML_ERROR_XML_DECL
- 该文档完全没有文档元素。
xml.parsers.expat. XML_ERROR_TEXT_DECL
- 解析外部实体中的文本语句时出错。
xml.parsers.expat. XML_ERROR_PUBLICID
- 在公共 ID 中找到了不允许的字符。
xml.parsers.expat. XML_ERROR_SUSPENDED
- 所请求的操作是在暂停的解析器上进行的，但不允许执行。这包括try提供其他 Importing 或停止解析器。
xml.parsers.expat. XML_ERROR_NOT_SUSPENDED
- 尚未暂停解析器时，try恢复解析器。
xml.parsers.expat. XML_ERROR_ABORTED
- 这不应报告给 Python 应用程序。
xml.parsers.expat. XML_ERROR_FINISHED
- 所请求的操作是在解析器上进行的，解析器已完成对 Importing 的解析，但不允许这样做。这包括try提供其他 Importing 或停止解析器。
xml.parsers.expat. XML_ERROR_SUSPEND_PE

Footnotes

[1]
- XML 输出中包含的编码字符串应符合适当的标准。例如，“ UTF-8”有效，但“ UTF8”无效。参见https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl和https://www.iana.org/assignments/character-sets/character-sets.xhtml。

Docs

Docs4dev

Title here

19.15. xml.parsers.expat —使用 Expat 的快速 XML 解析

19.15.1. XMLParser 对象

19.15.2. ExpatError 异常

19.15.3. Example

19.15.4. 内容模型说明

19.15.5. 扩展错误常量