19.12. xml.sax.handler — SAX 处理程序的 Base Class

2.0 版中的新Function。

SAX API 定义了四种处理程序：内容处理程序，DTD 处理程序，错误处理程序和实体解析器。应用程序通常只需要实现其事件感兴趣的那些接口即可。他们可以在单个对象或多个对象中实现接口。处理程序实现应继承自模块xml.sax.handler中提供的 Base Class，以便所有方法均获得默认实现。

• 类别 xml.sax.handler. ContentHandler

  • 这是 SAX 中的主要回调接口，并且对于应用程序来说是最重要的接口。该界面中事件的 Sequences 反映了文档中信息的 Sequences。

• 类别 xml.sax.handler. DTDHandler

  • 处理 DTD 事件。

此接口仅指定基本解析所需的那些 DTD 事件(未解析的实体和属性)。

• 类别 xml.sax.handler. EntityResolver

  • 解决实体的基本接口。如果创建实现此接口的对象，然后向解析器注册该对象，则解析器将调用对象中的方法来解析所有外部实体。

• 类别 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：所有元素名称，前缀，属性名称，命名空间 URI 和本地名称都使用内置的 intern 函数进行插入。

false：尽管名称可以是默认值，但名称不一定是 intern。

访问：(解析)只读； (不解析)读/写

• 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：包括所有外部常规(文本)实体。

否：不包括外部一般实体。

访问：(解析)只读； (不解析)读/写

• xml.sax.handler. feature_external_pes
  • 值："http://xml.org/sax/features/external-parameter-entities"

true：包括所有外部参数实体，包括外部 DTD 子集。

false：不包括任何外部参数实体，甚至不包括外部 DTD 子集。

访问：(解析)只读； (不解析)读/写

• xml.sax.handler. all_features

  • 所有Function列表。

• xml.sax.handler. property_lexical_handler

  • 值："http://xml.org/sax/properties/lexical-handler"

数据类型：xml.sax.sax2lib.LexicalHandler(Python 2 中不支持)

描述：一个可选的扩展处理程序，用于 Comments 等词法事件。

access: read/write

• xml.sax.handler. property_declaration_handler
  • 值："http://xml.org/sax/properties/declaration-handler"

数据类型：xml.sax.sax2lib.DeclHandler(Python 2 中不支持)

描述：一个可选的扩展处理程序，用于与 DTD 相关的事件，而不是符号和未解析的实体。

access: read/write

• xml.sax.handler. property_dom_node
  • 值："http://xml.org/sax/properties/dom-node"

数据类型：org.w3c.dom.Node(Python 2 不支持)

描述：解析时，如果这是 DOM 迭代器，则正在访问的当前 DOM 节点；不解析时，为迭代的根 DOM 节点。

访问：(解析)只读； (不解析)读/写

• xml.sax.handler. property_xml_string
  • 值："http://xml.org/sax/properties/xml-string"

数据类型：字符串

描述：作为当前事件源的字符 Literals 字符串。

access: read-only

• xml.sax.handler. all_properties
  • 所有已知属性名称的列表。

19.12.1. ContentHandler 对象

预计用户将继承ContentHandler子类以支持其应用程序。解析器在 Importing 文档中的相应事件上调用以下方法：

• ContentHandler. setDocumentLocator(* locator *)
  • 由解析器调用，为应用程序提供一个定位器，用于定位文档事件的起源。

强烈鼓励(尽管不是绝对必需)SAX 解析器提供定位器：如果这样做，则必须在调用 DocumentHandler 接口中的任何其他方法之前，pass调用此方法将定位器提供给应用程序。

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

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

• ContentHandler. startDocument ( )
  • 接收文档开始的通知。

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

• ContentHandler. endDocument ( )
  • 接收文档结尾的通知。

SAX 解析器将仅调用此方法一次，它将是解析期间最后调用的方法。解析器在放弃解析(由于不可恢复的错误)或到达 Importing 末尾之前，不得调用此方法。

• ContentHandler. startPrefixMapping(前缀，* uri *)
  • 开始前缀 URI 命名空间 Map 的范围。

来自该事件的信息对于正常的名称空间处理不是必需的：启用feature_namespacesFunction(默认值)时，SAX XML 阅读器将自动替换元素和属性名称的前缀。

但是，在某些情况下，当应用程序需要在字符数据或属性值中使用前缀时，无法安全地自动扩展它们； startPrefixMapping()和endPrefixMapping()事件将信息提供给应用程序，以便在必要时在这些上下文本身中扩展前缀。

请注意，不能保证startPrefixMapping()和endPrefixMapping()事件相对于彼此正确嵌套：所有startPrefixMapping()事件将在相应的startElement()事件之前发生，所有endPrefixMapping()事件将在相应的endElement()事件之后发生，但是不能保证 Sequences。

• ContentHandler. endPrefixMapping(前缀)
  • 结束前缀 URIMap 的范围。

有关详情，请参见startPrefixMapping()。此事件将始终在相应的endElement()事件之后发生，但不能保证endPrefixMapping()事件的 Sequences。

• ContentHandler. startElement(* name ， attrs *)
  • 在非命名空间模式下发出元素开始的 signal。

• name 参数包含作为字符串的元素类型的原始 XML 1.0 名称，而 attrs 参数包含包含元素属性的Attributes接口(请参见属性界面)的对象。解析器可以重复使用作为 attrs 传递的对象；保留对它的引用不是保留属性副本的可靠方法。要保留属性的副本，请使用 attrs *对象的copy()方法。

• ContentHandler. endElement(* name *)
  • 在非命名空间模式下发出元素结束的 signal。

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

• ContentHandler. startElementNS(* name ， qname ， attrs *)
  • 在命名空间模式下发出元素开始的 signal。

• name 参数包含作为(uri, localname)Tuples 的元素类型的名称， qname 参数包含在源文档中使用的原始 XML 1.0 名称，而 attrs 参数包含AttributesNS接口的实例(请参见AttributesNS 接口 )包含元素的属性。如果没有名称空间与元素关联，则 name 的 uri 组件将为None。解析器可以重复使用作为 attrs 传递的对象；保留对它的引用不是保留属性副本的可靠方法。要保留属性的副本，请使用 attrs *对象的copy()方法。

除非激活feature_namespace_prefixesFunction，否则解析器可以将* qname *参数设置为None。

• ContentHandler. endElementNS(* name ， qname *)
  • 在命名空间模式下发出元素结束的 signal。

• name 参数包含元素类型的名称，就像startElementNS()方法一样， qname *参数也是如此。

• ContentHandler. characters(* content *)
  • 接收字符数据的通知。

解析器将调用此方法来报告字符数据的每个块。 SAX 解析器可以在单个块中返回所有连续的字符数据，也可以将其拆分为几个块。但是，任何单个事件中的所有字符都必须来自同一外部实体，以便定位器提供有用的信息。

• content *可以是 Unicode 字符串或字节字符串； expat阅读器模块始终生成 Unicode 字符串。

• ContentHandler. ignorableWhitespace(空白)
  • 接收元素内容中可忽略空格的通知。

验证解析器必须使用此方法报告可忽略空白的每个块(请参阅 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属性的值。

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. ErrorHandler 对象

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

• ErrorHandler. error(* exception *)

  • 在解析器遇到可恢复错误时调用。如果此方法未引发异常，则可以 continue 解析，但是应用程序不应期望进一步的文档信息。允许解析器 continue 进行可能会允许在 Importing 文档中发现其他错误。

• ErrorHandler. fatalError(* exception *)

  • 当解析器遇到无法恢复的错误时调用；当此方法返回时，解析预计将终止。

• ErrorHandler. warning(* exception *)

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