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：可选地不执行命名空间处理（隐含命名空间前缀；默认）。

访问权限：（解析时）只读；（未解析时）读/写

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：报告所有验证错误（隐含外部通用实体和外部参数实体）。

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 接口的对象（请参阅 Attributes 接口），其中包含元素的属性。作为 attrs 传递的对象可能会被解析器重复使用；持有对它的引用并不是保留属性副本的可靠方法。要保留属性的副本，请使用 attrs 对象的 copy() 方法。

ContentHandler.endElement(name)

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

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

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)

指示命名空间模式下元素的结束。

与 startElementNS() 方法一样，name 参数包含元素类型的名称，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 方法设置 XMLReader 的 LexicalHandler，属性标识符为 'http://xml.org/sax/properties/lexical-handler'。

LexicalHandler.comment(content)

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

LexicalHandler.startDTD(name, public_id, system_id)

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

LexicalHandler.endDTD()

报告 DTD 声明的结束。

LexicalHandler.startCDATA()

报告 CDATA 标记部分的开始。

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

LexicalHandler.endCDATA()

报告 CDATA 标记部分的结束。