"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`（通常会被直接实例化）和处理器类也可
以从 :mod:"!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"。
