20.10. xml.sax.handler
— SAX处理程序的基类¶
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 接口)元件。如果没有命名空间与元素相关联,name 的 uri 组件将是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,而不是使用旧的 offset 和 length 参数分割内容。
-
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对象¶
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)¶ 当解析器向应用程序提供次要警告信息时调用。此方法返回时,解析将继续,并且文档信息将继续传递到应用程序。在此方法中引发异常将导致解析结束。