20.10. xml.sax.handler - SAX处理程序的基类

源代码： Lib / xml / sax / handler.py

SAX API定义了四种处理程序：内容处理程序，DTD处理程序，错误处理程序和实体解析程序。应用程序通常只需要实现他们感兴趣的事件的接口；它们可以在单个对象或多个对象中实现接口。Handler实现应该继承模块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
值："http://xml.org/sax/features/namespaces"
true：执行命名空间处理。
false：可选不执行命名空间处理（隐含命名空间前缀；默认）。
访问：（解析）只读； （不解析）读/写
xml.sax.handler.feature_namespace_prefixes
值："http://xml.org/sax/features/namespace-prefixes"
true：报告用于命名空间声明的原始前缀名称和属性。
false：不报告用于命名空间声明的属性，并且可选地不报告原始的前缀名称（默认）。
访问：（解析）只读； （不解析）读/写
xml.sax.handler.feature_string_interning
值："http://xml.org/sax/features/string-interning"
true：使用内建intern函数实现所有元素名称，前缀，属性名称，命名空间URI和本地名称。
false：名称不一定是interned，虽然他们可能是（默认）。
访问：（解析）只读； （不解析）读/写
xml.sax.handler.feature_validation
值："http://xml.org/sax/features/validation"
true：报告所有验证错误（暗示外部通用实体和外部参数实体）。
false：不报告验证错误。
访问：（解析）只读； （不解析）读/写
xml.sax.handler.feature_external_ges
值："http://xml.org/sax/features/external-general-entities"
true：包括所有外部常规（文本）实体。
false：不包括外部一般实体。
访问：（解析）只读； （不解析）读/写
xml.sax.handler.feature_external_pes
值："http://xml.org/sax/features/external-parameter-entities"
true：包括所有外部参数实体，包括外部DTD子集。
false：不包括任何外部参数实体，即使是外部DTD子集。
访问：（解析）只读； （不解析）读/写
xml.sax.handler.all_features

所有功能的列表。

xml.sax.handler.property_lexical_handler
值："http://xml.org/sax/properties/lexical-handler"
数据类型：xml.sax.sax2lib.LexicalHandler（在Python 2中不受支持）
description：用于词汇事件的可选扩展处理程序，如注释。
访问：读/写
xml.sax.handler.property_declaration_handler
值："http://xml.org/sax/properties/declaration-handler"
数据类型：xml.sax.sax2lib.DeclHandler（Python 2不支持）
description：除符号和未解析实体之外的DTD相关事件的可选扩展处理程序。
访问：读/写
xml.sax.handler.property_dom_node
值："http://xml.org/sax/properties/dom-node"
数据类型：org.w3c.dom.Node（Python 2不支持）
description：当解析时，如果这是DOM迭代器，则访问当前DOM节点；当不解析时，根DOM节点进行迭代。
访问：（解析）只读； （不解析）读/写
xml.sax.handler.property_xml_string
值："http://xml.org/sax/properties/xml-string"
数据类型：字符串
description：作为当前事件源的字面值字符串。
访问：只读
xml.sax.handler.all_properties

所有已知属性名称的列表。

20.10.1. ContentHandler Objects

用户需要子类化ContentHandler以支持他们的应用程序。解析器对输入文档中的相应事件调用以下方法：

ContentHandler.setDocumentLocator(locator)

由解析器调用以向应用程序提供用于定位文档事件的起源的定位器。

强烈鼓励（虽然不是绝对需要）提供定位器的SAX解析器：如果它这样做，它必须通过调用此方法在调用DocumentHandler接口中的任何其他方法之前提供定位器到应用程序。

定位器允许应用程序确定任何文档相关事件的结束位置，即使解析器未报告错误。通常，应用程序将使用此信息来报告其自身的错误（例如，与应用程序的业务规则不匹配的字符内容）。定位器返回的信息可能不足以用于搜索引擎。

注意，定位器将仅在调用该接口中的事件时返回正确的信息。应用程序不应尝试在任何其他时间使用它。

ContentHandler.startDocument()

接收文档开头的通知。

SAX解析器将只调用此方法一次，在此接口或DTDHandler中的任何其他方法（除了setDocumentLocator()）之前。

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接口的对象The Attributes Interface）包含元素的属性。作为attrs传递的对象可以由解析器重用；保持对它的引用不是保持属性的副本的可靠方式。要保留属性的副本，请使用attrs对象的copy()方法。

ContentHandler.endElement(name)

以非命名空间模式表示元素的结尾。

name参数包含元素类型的名称，与startElement()事件一样。

ContentHandler.startElementNS(name, qname, attrs)

在命名空间模式中用信号通知元素的开始。

name参数包含（uri， localname）元组类型的名称， qname参数包含源文档中使用的原始XML 1.0名称，attrs参数保存AttributesNS界面的实例（请参阅The AttributesNS Interface）包含元素的属性。如果没有与元素相关联的命名空间，则名称的uri组件将为None。作为attrs传递的对象可以由解析器重用；保持对它的引用不是保持属性的副本的可靠方式。要保留属性的副本，请使用attrs对象的copy()方法。

解析器可以将qname参数设置为None，除非激活feature_namespace_prefixes功能。

ContentHandler.endElementNS(name, qname)

在命名空间模式中用信号通知元素的结尾。

name参数包含元素类型的名称，与startElementNS()方法一样，与qname参数一样。

ContentHandler.characters(content)

接收字符数据的通知。

解析器将调用此方法来报告每个字符数据块。SAX解析器可以返回单个块中的所有连续字符数据，或者它们可以将其拆分成几个块；然而，任何单个事件中的所有字符必须来自相同的外部实体，以便定位器提供有用的信息。

内容可以是字符串或字节实例； expat阅读器模块总是生成字符串。

注意

Python XML Special Interest Group提供的较早的SAX 1接口为此方法使用了更类似Java的接口。由于从Python使用的大多数解析器没有利用旧的接口，选择更简单的声明来替换它。要将旧代码转换为新界面，请使用content而不是使用旧的偏移和长度参数对内容进行切片。

ContentHandler.ignorableWhitespace(whitespace)

在元素内容中接收可忽略的空格的通知。

验证解析器必须使用此方法来报告每个块的可忽略的空格（请参阅W3C XML 1.0建议，2.10节）：如果非验证解析器能够解析和使用内容模型，则它们也可以使用此方法。

SAX解析器可以返回单个块中的所有连续空格，或者它们可以将其拆分成几个块；然而，任何单个事件中的所有字符必须来自同一外部实体，以便定位器提供有用的信息。

ContentHandler.processingInstruction(target, data)

接收处理指令的通知。

对于找到的每个处理指令，解析器将调用该方法一次：注意，处理指令可以发生在主文档元素之前或之后。

SAX解析器不应该使用此方法报告XML声明（XML 1.0，第2.8节）或文本声明（XML 1.0，第4.3.1节）。

ContentHandler.skippedEntity(name)

接收跳过的实体的通知。

对于每个跳过的实体，解析器将调用此方法一次。非验证处理器可以跳过实体，如果它们没有看到声明（因为例如实体在外部DTD子集中声明）。所有处理器可能会跳过外部实体，具体取决于feature_external_ges和feature_external_pes属性的值。

20.10.2. DTDHandler Objects

DTDHandler实例提供以下方法：

DTDHandler.notationDecl(name, publicId, systemId)

处理符号声明事件。

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

处理未解析的实体声明事件。

20.10.3. EntityResolver Objects

EntityResolver.resolveEntity(publicId, systemId)

解析实体的系统标识符，并返回要作为字符串读取的系统标识符或要读取的InputSource。默认实现返回systemId。

20.10.4. ErrorHandler Objects

具有此接口的对象用于从XMLReader接收错误和警告信息。如果创建实现此接口的对象，则使用XMLReader注册该对象，解析器将调用对象中的方法以报告所有警告和错误。有三个级别的错误可用：警告，（可能）可恢复错误和不可恢复的错误。所有方法都将SAXParseException作为唯一参数。通过提高传入的异常对象，错误和警告可能会转换为异常。

ErrorHandler.error(exception)

当解析器遇到可恢复的错误时调用。如果此方法不引发异常，则解析可以继续，但应用程序不应该期望进一步的文档信息。允许解析器继续可以允许在输入文档中发现附加的错误。

ErrorHandler.fatalError(exception)

在解析器遇到错误时调用，无法从中恢复；此方法返回时，解析预期会终止。

ErrorHandler.warning(exception)

当解析器向应用程序提供次要警告信息时调用。此方法返回时，解析将继续，并且文档信息将继续传递到应用程序。在此方法中引发异常将导致解析结束。