Skip to main content

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:所有元素名称,前缀,属性名称,命名空间URI和本地名称都使用内置的intern函数实现。
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对象

用户需要子类化 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 接口(见 Attributes 接口)的对象。作为 attrs 传递的对象可以被解析器重用;保持对它的引用不是保持属性的副本的可靠方式。要保留属性的副本,请使用 attrs 对象的 copy() 方法。

ContentHandler.endElement(name)

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

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

ContentHandler.startElementNS(name, qname, attrs)

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

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

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

ContentHandler.endElementNS(name, qname)

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

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

ContentHandler.characters(content)

接收字符数据的通知。

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

content 可以是字符串或字节实例; expat 阅读器模块总是产生字符串。

注解

Python XML Special Interest Group提供的较早的SAX 1接口为此方法使用了更类似Java的接口。由于从Python使用的大多数解析器没有利用旧的接口,选择更简单的签名来替换它。要将旧代码转换为新接口,请使用 content,而不是使用旧的 offsetlength 参数分割内容。

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

20.10.2. DTDHandler对象

DTDHandler 实例提供以下方法:

DTDHandler.notationDecl(name, publicId, systemId)

处理符号声明事件。

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

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

20.10.3. EntityResolver对象

EntityResolver.resolveEntity(publicId, systemId)

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

20.10.4. ErrorHandler对象

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

ErrorHandler.error(exception)

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

ErrorHandler.fatalError(exception)

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

ErrorHandler.warning(exception)

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