"xml.sax" --- 支持 SAX2 解析器
******************************

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

======================================================================

"xml.sax" 包提供多个模块，它们在 Python 上实现了用于 XML (SAX)  接口的
简单 API。 这个包本身为  SAX API 用户提供了一些最常用的 SAX 异常和便捷
函数。

警告:

  "xml.sax" 模块对于恶意构建的数据是不安全的。 如果你需要解析不受信任
  或未经身份验证的数据，请参阅 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"。
