# 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)

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