# `xml.sax` --- SAX2 解析器支持

源代码: Lib/xml/sax/__init__.py

`xml.sax` 包提供了许多实现 XML 简单 API (SAX) 接口的模块供 Python 使用。 这个包本身提供了 SAX 异常和 SAX API 用户最常使用的便捷函数。

备注

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

在 3.7.1 版本发生变更: SAX 解析器默认不会再处理通用外部实体以便提升安全性。 在此之前，解析器会创建网络连接来获取远程文件或是从文件系统加载本地文件以处理 DTD 和实体。 此特性可通过在解析器对象上调用 `setFeature()` 方法并传入参数 `feature_external_ges` 来重新启用。

可用的便捷函数如下所列:

xml.sax.make_parser(parser_list=[])

  创建并返回一个 SAX `XMLReader` 对象。 将返回第一个被找到的解析器。 如果提供了 parser_list，它必须为一个包含字符串的可迭代对象，这些字符串指定了具有名为 `create_parser()` 函数的模块。 在 parser_list 中列出的模块将在默认解析器列表中的模块之前被使用。

  在 3.8 版本发生变更: parser_list 参数可以是任意可迭代对象，而不一定是列表。

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

  创建一个 SAX 解析器并用它来解析文档。 用于传入文档的 filename_or_stream 可以是一个文件名或文件对象。 handler 形参必须是一个 SAX `ContentHandler` 实例。 如果给出了 error_handler，则它必须是一个 SAX `ErrorHandler` 实例；如果省略，则对于任何错误都将引发 `SAXParseException`。 此函数没有返回值；所有操作必须由传入的 handler 来完成。

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

  类似于 `parse()`，但解析对象是作为形参传入的缓冲区 string。 string 必须为 `str` 实例或者 bytes-like object。

  在 3.5 版本发生变更: 增加了对 `str` 实例的支持。

典型的 SAX 应用程序会使用三种对象：读取器、处理器和输入源。 “读取器”在此上下文中与解析器同义，即某个从输入源读取字节或字符，并产生事件序列的代码段。 事件随后将被分发给处理器对象，即由读取器调用处理器上的某个方法。 因此 SAX 应用程序必须获取一个读取器对象，创建或打开输入源，创建处理器，并将这些对象连接到一起。 作为准备工作的最后一步，将调用读取器来解析输入内容。 在解析过程中，会根据来自输入数据的结构化和语法化事件来调用处理器对象上的方法。

对于这些对象，只有接口才是重要的；它们通常不由应用程序本身来实例化。 由于 Python 没有显式的接口概念，它们在形式上被表示为类，但应用程序可以使用不继承自所提供的类的具体实现。 `InputSource`、`Locator`、`Attributes`、`AttributesNS` 和 `XMLReader` 接口是在 `xml.sax.xmlreader` 模块中定义的。 处理器接口是在 `xml.sax.handler` 中定义的。 为方便起见，`InputSource` (通常会被直接实例化) 和处理器类也可以从 `xml.sax` 获取。 下面将介绍这些接口。

除了这些类之外，`xml.sax` 还提供了以下异常类。

exception xml.sax.SAXException(msg, exception=None)

  封装某个 XML 错误或警告。 这个类可以包含来自 XML 解析器或应用程序的基本错误或警告信息：它可以被子类化以提供额外的功能或是添加本地化信息。 请注意虽然在 `ErrorHandler` 接口中定义的处理器可以接收该异常的实例，但是并不要求实际引发该异常 --- 它也可以被用作信息的容器。

  当实例化时，msg 应当是适合人类阅读的错误描述。 如果给出了可选的 exception 形参，它应当为 `None` 或者是被解析代码所捕获并将作为信息传递的异常。

  这是其他 SAX 异常类的基类。

exception xml.sax.SAXParseException(msg, exception, locator)

  `SAXException` 的子类，针对解析错误引发。 这个类的实例会被传递给 SAX `ErrorHandler` 接口的方法来提供关于解析错误的信息。 这个类支持 SAX `Locator` 接口以及 `SAXException` 接口。

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

  `SAXException` 的子类，当 SAX `XMLReader` 遇到不可识别的特性或属性时引发。 SAX 应用程序和扩展可能会出于类似目的而使用这个类。

exception xml.sax.SAXNotSupportedException(msg, exception=None)

  `SAXException` 的子类，当 SAX `XMLReader` 被要求启用某个不受支持的特性，或者将某个属性设为具体实现不支持的值时引发。 SAX 应用程序和扩展可能会出于类似目的而使用这个类。

参见

SAX: The Simple API for XML

  这个网站是 SAX API 定义的焦点。 它提供了一个 Java 实现以及在线文档。 还包括其他实现的链接和历史信息。

`xml.sax.handler` 模块

  应用程序所提供对象的接口定义。

`xml.sax.saxutils` 模块

  可在 SAX 应用程序中使用的便捷函数。

`xml.sax.xmlreader` 模块

  解析器所提供对象的接口定义。

## SAXException 对象

`SAXException` 异常类支持下列方法:

SAXException.getMessage()

  返回描述错误条件的适合人类阅读的消息。

SAXException.getException()

  返回一个封装的异常对象或者 `None`。