xml.sax.handler

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_namespacesxml.sax.handler.feature_namespace_prefixesxml.sax.handler.feature_string_interningxml.sax.handler.feature_validationxml.sax.handler.feature_external_gesxml.sax.handler.feature_external_pesxml.sax.handler.all_features

所有功能列表。

xml.sax.handler.property_lexical_handlerxml.sax.handler.property_declaration_handlerxml.sax.handler.property_dom_nodexml.sax.handler.property_xml_stringxml.sax.handler.all_properties

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

1. ContentHandler对象

用户需要继承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接口的对象（请参阅属性接口）。 作为attrs传递的对象可以被解析器重用; 坚持引用它并不是保持属性副本的可靠方法。 要保留属性的副本，请使用attrs对象的copy（）方法。

ContentHandler.endElement(name)

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

该名称 参数中包含的元素类型的名称，就像用startElement()事件。

ContentHandler.startElementNS(name, qname, attrs)

在名称空间模式中指定元素的开始。

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

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

ContentHandler.endElementNS(name, qname)

以命名空间模式标记元素的结尾。

name参数包含元素类型的名称，就像startElementNS（）方法一样，同样也包含qname参数。

ContentHandler.characters(content)

接收字符数据的通知。

解析器将调用此方法来报告每个字符数据块。SAX解析器可能会将所有连续的字符数据返回到单个块中，或者它们可能会将其分割为多个块; 但是，任何单个事件中的所有字符必须来自相同的外部实体，以便定位器提供有用的信息。

内容 可能是一个Unicode字符串或一个字节字符串; 该expat读写器模块总是会产生Unicode字符串。

注意

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

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属性的值。

2. DTDHandler对象

DTDHandler 实例提供以下方法：

DTDHandler.notationDecl(name, publicId, systemId)

处理符号声明事件。

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

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

3. EntityResolver对象

EntityResolver.resolveEntity(publicId, systemId)

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

4. ErrorHandler对象

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

ErrorHandler.error(exception)

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

ErrorHandler.fatalError(exception)

当解析器遇到错误时调用它无法从中恢复; 当此方法返回时，预计解析将终止。

ErrorHandler.warning(exception)

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