xml.sax.handler — SAX 处理器基类

源代码: Lib/xml/sax/handler.py

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

解析器用于向应用程序呈现错误和警告消息的接口。此对象的方法控制错误是立即转换为异常还是以其他方式处理。

class xml.sax.handler.LexicalHandler

解析器用于表示许多应用程序可能不感兴趣的低频事件的接口。

除了这些类，xml.sax.handler 还提供了特性和属性名称的符号常量。

xml.sax.handler.feature_namespaces
值: "http://xml.org/sax/features/namespaces"
true: 执行命名空间处理。
false: 可选地不执行命名空间处理（暗示 namespace-prefixes；默认）。
访问: (解析时) 只读；(非解析时) 读/写
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: 名称不一定被内部化，尽管它们可能被内部化（默认）。
访问: (解析时) 只读；(非解析时) 读/写
xml.sax.handler.feature_validation
值: "http://xml.org/sax/features/validation"
true: 报告所有验证错误（暗示 external-general-entities 和 external-parameter-entities）。
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.handler.LexicalHandler (Python 2 不支持)
描述: 一个可选的用于处理注释等词法事件的扩展处理器。
访问: 读/写
xml.sax.handler.property_declaration_handler
值: "http://xml.org/sax/properties/declaration-handler"
数据类型: xml.sax.sax2lib.DeclHandler (Python 2 不支持)
描述: 一个可选的用于处理与 DTD 相关事件（除了符号和未解析实体）的扩展处理器。
访问: 读/写
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"
数据类型: Bytes
描述: 当前事件源的字面字符串。
访问: 只读
xml.sax.handler.all_properties

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

ContentHandler 对象

用户需要子类化 ContentHandler 来支持其应用程序。以下方法在输入文档中发生相应事件时由解析器调用

ContentHandler.setDocumentLocator(locator)

由解析器调用，向应用程序提供一个定位器，用于定位文档事件的来源。

强烈建议 SAX 解析器（尽管并非绝对要求）提供定位器：如果提供了，则必须在调用 DocumentHandler 接口中的任何其他方法之前（setDocumentLocator() 除外）通过调用此方法向应用程序提供定位器。

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

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

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)

在非命名空间模式下表示元素的结束。

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

ContentHandler.startElementNS(name, qname, attrs)

在命名空间模式下表示元素的开始。

name 参数包含元素类型的名称，作为 (uri, localname) 元组，qname 参数包含源文档中使用的原始 XML 1.0 名称，attrs 参数包含 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 特别兴趣小组提供的早期 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 属性的值。

DTDHandler 对象

DTDHandler 实例提供以下方法

DTDHandler.notationDecl(name, publicId, systemId)

处理符号声明事件。

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

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

EntityResolver 对象

EntityResolver.resolveEntity(publicId, systemId)

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

ErrorHandler 对象

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

ErrorHandler.error(exception)

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

ErrorHandler.fatalError(exception)

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

ErrorHandler.warning(exception)

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

LexicalHandler 对象

可选的 SAX2 词法事件处理器。

此处理器用于获取 XML 文档的词法信息。词法信息包括描述文档编码、嵌入在文档中的 XML 注释以及 DTD 和任何 CDATA 节的边界。词法处理器以与内容处理器相同的方式使用。

通过使用 setProperty 方法和属性标识符 'http://xml.org/sax/properties/lexical-handler' 来设置 XMLReader 的 LexicalHandler。

LexicalHandler.comment(content)

报告文档中任何位置（包括 DTD 和文档元素外部）的注释。

LexicalHandler.startDTD(name, public_id, system_id)

如果文档具有关联的 DTD，则报告 DTD 声明的开始。

LexicalHandler.endDTD()

报告 DTD 声明的结束。

LexicalHandler.startCDATA()

报告 CDATA 标记节的开始。

CDATA 标记节的内容将通过字符处理器报告。

LexicalHandler.endCDATA()

报告 CDATA 标记节的结束。