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"

数据类型：字节

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

访问权限：只读

xml.sax.handler.all_properties

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

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 接口的对象（请参阅 属性接口），其中包含元素的属性。作为 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() 方法。

除非激活 feature_namespace_prefixes 功能，否则解析器可能会将 qname 参数设置为 None。

ContentHandler.endElementNS(name, qname)

发出在命名空间模式下元素结束的信号。

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

ContentHandler.characters(content)

接收字符数据的通知。

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

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

注意

Python XML 特殊兴趣小组提供的早期 SAX 1 接口为此方法使用了更类似 Java 的接口。由于从 Python 使用的大多数解析器都没有利用旧的接口，因此选择了更简单的签名来替换它。要将旧代码转换为新接口，请使用 content 而不是使用旧的 offset 和 length 参数来切片 content。

ContentHandler.ignorableWhitespace(whitespace)

接收元素内容中可忽略的空格的通知。

验证解析器必须使用此方法来报告每个可忽略的空格块（请参阅 W3C XML 1.0 建议，第 2.10 节）：如果非验证解析器能够解析和使用内容模型，它们也可以使用此方法。

SAX 解析器可能会在一个块中返回所有连续的空格，或者可能会将其拆分为多个块；但是，任何单个事件中的所有字符都必须来自同一个外部实体，以便 Locator 提供有用的信息。

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 部分的节边界。词法处理程序的使用方式与内容处理程序相同。

通过使用属性标识符 'http://xml.org/sax/properties/lexical-handler' 的 setProperty 方法设置 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 标记部分的结束。