19.12. xml.sax.handler — SAX 处理程序的基类 — Python 文档
19.12. xml.sax.handler — SAX 处理程序的基类
2.0 版中的新功能。
SAX API 定义了四种处理程序：内容处理程序、DTD 处理程序、错误处理程序和实体解析程序。 应用程序通常只需要实现那些他们感兴趣的事件的接口； 它们可以在单个对象或多个对象中实现接口。 处理程序实现应从模块 xml.sax.handler 中提供的基类继承，以便所有方法获得默认实现。
- class xml.sax.handler.ContentHandler
- 这是 SAX 中的主要回调接口，也是对应用程序最重要的接口。 此界面中的事件顺序反映了文档中信息的顺序。
- class xml.sax.handler.DTDHandler
处理 DTD 事件。
此接口仅指定基本解析（未解析的实体和属性）所需的那些 DTD 事件。
- class xml.sax.handler.EntityResolver
- 解析实体的基本接口。 如果您创建一个实现此接口的对象，然后将对象注册到您的解析器，解析器将调用您对象中的方法来解析所有外部实体。
- class xml.sax.handler.ErrorHandler
- 解析器用于向应用程序显示错误和警告消息的接口。 此对象的方法控制错误是立即转换为异常还是以其他方式处理。
除了这些类之外，xml.sax.handler 还为特征和属性名称提供符号常量。
- xml.sax.handler.feature_namespaces
-
true：执行命名空间处理。
false：可选择不执行命名空间处理（暗示命名空间前缀；默认）。
访问：（解析）只读； （不解析）读/写
- xml.sax.handler.feature_namespace_prefixes
-
true：报告用于命名空间声明的原始前缀名称和属性。
false：不报告用于命名空间声明的属性，并且可选择不报告原始前缀名称（默认）。
访问：（解析）只读； （不解析）读/写
- xml.sax.handler.feature_string_interning
-
true：所有元素名称、前缀、属性名称、命名空间 URI 和本地名称都使用内置的 intern 函数进行实习。
false：名称不一定是实习的，尽管它们可能是（默认）。
访问：（解析）只读； （不解析）读/写
- xml.sax.handler.feature_validation
-
true：报告所有验证错误（暗示 external-general-entities 和 external-parameter-entities）。
false：不报告验证错误。
访问：（解析）只读； （不解析）读/写
- xml.sax.handler.feature_external_ges
-
true：包括所有外部通用（文本）实体。
false：不包括外部通用实体。
访问：（解析）只读； （不解析）读/写
- xml.sax.handler.feature_external_pes
-
true：包括所有外部参数实体，包括外部 DTD 子集。
false：不包括任何外部参数实体，即使是外部 DTD 子集。
访问：（解析）只读； （不解析）读/写
- xml.sax.handler.all_features
- 所有功能的列表。
- xml.sax.handler.property_lexical_handler
-
数据类型：xml.sax.sax2lib.LexicalHandler（Python 2 不支持）
描述：一个可选的扩展处理程序，用于诸如注释之类的词法事件。
访问：读/写
- xml.sax.handler.property_declaration_handler
-
数据类型：xml.sax.sax2lib.DeclHandler（Python 2 不支持）
描述：除符号和未解析实体之外的 DTD 相关事件的可选扩展处理程序。
访问：读/写
- xml.sax.handler.property_dom_node
-
数据类型：org.w3c.dom.Node（Python 2 不支持）
描述：解析时，如果这是一个DOM迭代器，当前正在访问的DOM节点； 不解析时，迭代的根DOM节点。
访问：（解析）只读； （不解析）读/写
- xml.sax.handler.property_xml_string
-
数据类型：字符串
描述：作为当前事件源的文字字符串。
访问：只读
- xml.sax.handler.all_properties
- 所有已知属性名称的列表。
19.12.1. 内容处理程序对象
用户应该继承 ContentHandler 以支持他们的应用程序。 解析器对输入文档中的适当事件调用以下方法：
- ContentHandler.setDocumentLocator(locator)
由解析器调用，为应用程序提供一个定位器来定位文档事件的来源。
强烈建议 SAX 解析器（尽管不是绝对需要）提供定位器：如果这样做，它必须在调用 DocumentHandler 接口中的任何其他方法之前通过调用此方法将定位器提供给应用程序。
定位器允许应用程序确定任何与文档相关的事件的结束位置，即使解析器没有报告错误。 通常，应用程序将使用此信息报告其自身的错误（例如与应用程序的业务规则不匹配的字符内容）。 定位器返回的信息可能不足以用于搜索引擎。
请注意，定位器仅在调用此接口中的事件期间才会返回正确的信息。 应用程序不应在任何其他时间尝试使用它。
- ContentHandler.startDocument()
接收文档开始的通知。
在此接口或 DTDHandler 中的任何其他方法之前（除了 setDocumentLocator()），SAX 解析器只会调用此方法一次。
- ContentHandler.endDocument()
接收文档结束的通知。
SAX 解析器只会调用此方法一次，并且它将是解析过程中调用的最后一个方法。 解析器在放弃解析（由于不可恢复的错误）或到达输入末尾之前不应调用此方法。
- ContentHandler.startPrefixMapping(prefix, uri)
开始前缀-URI 命名空间映射的范围。
来自此事件的信息对于正常的命名空间处理不是必需的：当启用
feature_namespaces功能（默认）时，SAX XML 阅读器将自动替换元素和属性名称的前缀。然而，在某些情况下，当应用程序需要在字符数据或属性值中使用前缀时，它们无法安全地自动扩展； startPrefixMapping() 和 endPrefixMapping() 事件向应用程序提供信息，以在必要时扩展这些上下文中的前缀。
请注意，startPrefixMapping() 和 endPrefixMapping() 事件不能保证相对于彼此正确嵌套：所有 startPrefixMapping() 事件将在对应的 startElement() 事件，以及所有的 endPrefixMapping() 事件都会在对应的 endElement() 事件之后发生，但不保证它们的顺序。
- ContentHandler.endPrefixMapping(prefix)
结束前缀-URI 映射的范围。
有关详细信息，请参阅 startPrefixMapping()。 此事件将始终发生在相应的 endElement() 事件之后，但不保证 endPrefixMapping() 事件的顺序。
- ContentHandler.startElement(name, attrs)
在非命名空间模式下表示元素的开始。
name 参数包含元素类型的原始 XML 1.0 名称作为字符串，attrs 参数包含
Attributes接口的对象（请参阅 属性接口) 包含元素的属性。 作为 attrs 传递的对象可以被解析器重用； 保留对它的引用并不是保留属性副本的可靠方法。 要保留属性的副本，请使用 attrs 对象的 copy() 方法。
- ContentHandler.endElement(name)
在非命名空间模式下发出元素结束的信号。
name 参数包含元素类型的名称，就像 startElement() 事件一样。
- ContentHandler.startElementNS(name, qname, attrs)
表示命名空间模式下元素的开始。
name 参数包含作为
(uri, localname)元组的元素类型名称，qname 参数包含源文档中使用的原始 XML 1.0 名称，[ X184X]attrs 参数包含一个包含元素属性的AttributesNS接口实例（参见 The AttributesNS Interface）。 如果没有命名空间与元素关联，则 name 的 uri 组件将为None。 作为 attrs 传递的对象可以被解析器重用； 保留对它的引用并不是保留属性副本的可靠方法。 要保留属性的副本，请使用 attrs 对象的 copy() 方法。解析器可以将 qname 参数设置为
None，除非feature_namespace_prefixes功能被激活。
- ContentHandler.endElementNS(name, qname)
表示命名空间模式下元素的结束。
name 参数包含元素类型的名称，就像 startElementNS() 方法一样，qname 参数也是如此。
- ContentHandler.characters(content)
接收字符数据的通知。
Parser 将调用此方法来报告每个字符数据块。 SAX 解析器可以在单个块中返回所有连续的字符数据，也可以将其拆分为多个块； 然而，任何单个事件中的所有角色都必须来自同一个外部实体，以便定位器提供有用的信息。
content 可以是Unicode字符串或字节字符串；
expat阅读器模块始终生成 Unicode 字符串。笔记
Python XML Special Interest Group 提供的早期 SAX 1 接口为此方法使用了更类似于 Java 的接口。 由于 Python 中使用的大多数解析器都没有利用旧接口，因此选择了更简单的签名来代替它。 要将旧代码转换为新接口，请使用 content 而不是使用旧的 offset 和 length 参数对内容进行切片。
- ContentHandler.ignorableWhitespace(whitespace)
接收元素内容中可忽略空格的通知。
验证解析器必须使用此方法报告每个可忽略空格块（请参阅 W3C XML 1.0 建议，第 2.10 节）：如果非验证解析器能够解析和使用内容模型，则它们也可以使用此方法。
SAX 解析器可能会在单个块中返回所有连续的空白，或者它们可能会将其拆分为多个块； 然而，任何单个事件中的所有角色都必须来自同一个外部实体，以便定位器提供有用的信息。
- ContentHandler.processingInstruction(target, data)
接收处理指令的通知。
Parser 会为找到的每个处理指令调用一次此方法：注意处理指令可能出现在主文档元素之前或之后。
SAX 解析器不应使用此方法报告 XML 声明（XML 1.0，第 2.8 节）或文本声明（XML 1.0，第 4.3.1 节）。
- ContentHandler.skippedEntity(name)
接收跳过实体的通知。
解析器将为跳过的每个实体调用一次此方法。 非验证处理器如果没有看到声明可能会跳过实体（例如，因为实体是在外部 DTD 子集中声明的）。 所有处理器都可以跳过外部实体，具体取决于
feature_external_ges和feature_external_pes属性的值。
19.12.2. DTDHandler 对象
DTDHandler 实例提供以下方法：
- DTDHandler.notationDecl(name, publicId, systemId)
- 处理符号声明事件。
- DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)
- 处理未解析的实体声明事件。
19.12.3. EntityResolver 对象
- EntityResolver.resolveEntity(publicId, systemId)
- 解析实体的系统标识符并返回要作为字符串读取的系统标识符或要读取的 InputSource。 默认实现返回 systemId。
19.12.4. 错误处理程序对象
具有此接口的对象用于从 XMLReader 接收错误和警告信息。 如果您创建一个实现此接口的对象，然后使用您的 XMLReader 注册该对象，解析器将调用您对象中的方法来报告所有警告和错误。 有可用的三个级别的错误：警告、（可能）可恢复的错误和不可恢复的错误。 所有方法都将 SAXParseException 作为唯一参数。 错误和警告可以通过引发传入的异常对象转换为异常。
- ErrorHandler.error(exception)
- 当解析器遇到可恢复的错误时调用。 如果此方法不引发异常，解析可能会继续，但应用程序不应期望进一步的文档信息。 允许解析器继续可能允许在输入文档中发现其他错误。
- ErrorHandler.fatalError(exception)
- 当解析器遇到无法恢复的错误时调用； 当此方法返回时，解析预计将终止。
- ErrorHandler.warning(exception)
- 当解析器向应用程序提供次要警告信息时调用。 当此方法返回时，解析预计会继续，并且文档信息将继续传递给应用程序。 在此方法中引发异常将导致解析结束。
