xml.sax.handler — SAX 处理程序的 Base Class

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

SAX API 定义了四种处理程序：内容处理程序，DTD 处理程序，错误处理程序和实体解析器。应用程序通常只需要实现其事件感兴趣的那些接口即可。他们可以在单个对象或多个对象中实现接口。处理程序实现应继承自模块xml.sax.handler中提供的 Base Class，以便所有方法均获得默认实现。

  • 类别 xml.sax.handler. ContentHandler

    • 这是 SAX 中的主要回调接口，并且对于应用程序来说是最重要的接口。该界面中事件的 Sequences 反映了文档中信息的 Sequences。

  • 类别 xml.sax.handler. DTDHandler

    • 处理 DTD 事件。

此接口仅指定基本解析所需的那些 DTD 事件(未解析的实体和属性)。

  • 类别 xml.sax.handler. EntityResolver

    • 解决实体的基本接口。如果创建实现此接口的对象，然后向解析器注册该对象，则解析器将调用对象中的方法来解析所有外部实体。

  • 类别 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：尽管名称可以是默认值，但名称不一定是 intern。

访问：(解析)只读； (不解析)读/写

  • 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：包括所有外部常规(文本)实体。

否：不包括外部一般实体。

访问：(解析)只读； (不解析)读/写

  • xml.sax.handler. feature_external_pes
    • 值："http://xml.org/sax/features/external-parameter-entities"

true：包括所有外部参数实体，包括外部 DTD 子集。

false：不包括任何外部参数实体，甚至不包括外部 DTD 子集。

访问：(解析)只读； (不解析)读/写

  • xml.sax.handler. all_features

    • 所有Function列表。

  • xml.sax.handler. property_lexical_handler

    • 值："http://xml.org/sax/properties/lexical-handler"

数据类型：xml.sax.sax2lib.LexicalHandler(Python 2 中不支持)

描述：一个可选的扩展处理程序，用于 Comments 等词法事件。

access: read/write

  • xml.sax.handler. property_declaration_handler
    • 值："http://xml.org/sax/properties/declaration-handler"

数据类型：xml.sax.sax2lib.DeclHandler(Python 2 中不支持)

描述：一个可选的扩展处理程序，用于与 DTD 相关的事件，而不是符号和未解析的实体。

access: read/write

  • 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"

数据类型：字符串

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

access: read-only

  • xml.sax.handler. all_properties
    • 所有已知属性名称的列表。

ContentHandler Objects

预计用户将继承ContentHandler子类以支持其应用程序。解析器在 Importing 文档中的相应事件上调用以下方法：

  • ContentHandler. setDocumentLocator(* locator *)
    • 由解析器调用，为应用程序提供一个定位器，用于定位文档事件的起源。

强烈鼓励(尽管不是绝对必需)SAX 解析器提供定位器：如果这样做，则必须在调用 DocumentHandler 接口中的任何其他方法之前，pass调用此方法将定位器提供给应用程序。

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

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

  • ContentHandler. startDocument ( )
    • 接收文档开始的通知。

SAX 解析器将仅在此接口或 DTDHandler 中的任何其他方法(setDocumentLocator()除外)之前调用一次此方法。

  • ContentHandler. endDocument ( )
    • 接收文档结尾的通知。

SAX 解析器将仅调用此方法一次，它将是解析期间最后调用的方法。解析器在放弃解析(由于不可恢复的错误)或到达 Importing 末尾之前，不得调用此方法。

  • ContentHandler. startPrefixMapping(前缀，* uri *)
    • 开始前缀 URI 命名空间 Map 的范围。

来自该事件的信息对于正常的名称空间处理不是必需的：启用feature_namespacesFunction(默认值)时，SAX XML 阅读器将自动替换元素和属性名称的前缀。

但是，在某些情况下，当应用程序需要在字符数据或属性值中使用前缀时，无法安全地自动扩展它们； startPrefixMapping()和endPrefixMapping()事件将信息提供给应用程序，以便在必要时在这些上下文本身中扩展前缀。

请注意，不能保证startPrefixMapping()和endPrefixMapping()事件相对于彼此正确嵌套：所有startPrefixMapping()事件将在相应的startElement()事件之前发生，所有endPrefixMapping()事件将在相应的endElement()事件之后发生，但是不能保证 Sequences。

  • ContentHandler. endPrefixMapping(前缀)
    • 结束前缀 URIMap 的范围。

有关详情，请参见startPrefixMapping()。此事件将始终在相应的endElement()事件之后发生，但不能保证endPrefixMapping()事件的 Sequences。

  • ContentHandler. startElement(* name ， attrs *)
    • 在非命名空间模式下发出元素开始的 signal。
  • name 参数包含作为字符串的元素类型的原始 XML 1.0 名称，而 attrs 参数包含包含元素属性的Attributes接口(请参见属性界面)的对象。解析器可以重复使用作为 attrs 传递的对象；保留对它的引用不是保留属性副本的可靠方法。要保留属性的副本，请使用 attrs *对象的copy()方法。
  • ContentHandler. endElement(* name *)
    • 在非命名空间模式下发出元素结束的 signal。

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

  • ContentHandler. startElementNS(* name ， qname ， attrs *)
    • 在命名空间模式下发出元素开始的 signal。
  • name 参数包含作为(uri, localname)Tuples 的元素类型的名称， qname 参数包含在源文档中使用的原始 XML 1.0 名称，而 attrs 参数包含AttributesNS接口的实例(请参见AttributesNS 接口 )包含元素的属性。如果没有名称空间与元素关联，则 name 的 uri 组件将为None。解析器可以重复使用作为 attrs 传递的对象；保留对它的引用不是保留属性副本的可靠方法。要保留属性的副本，请使用 attrs *对象的copy()方法。

除非激活feature_namespace_prefixesFunction，否则解析器可以将* qname *参数设置为None。

  • ContentHandler. endElementNS(* name ， qname *)
    • 在命名空间模式下发出元素结束的 signal。
  • name 参数包含元素类型的名称，就像startElementNS()方法一样， qname *参数也是如此。
  • ContentHandler. characters(* content *)
    • 接收字符数据的通知。

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

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

Note

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

  • ContentHandler. ignorableWhitespace(空白)
    • 接收元素内容中可忽略空格的通知。

验证解析器必须使用此方法报告可忽略空白的每个块(请参阅 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 Objects

DTDHandler实例提供以下方法：

  • DTDHandler. notationDecl(* name ， publicId ， systemId *)

    • 处理符号语句事件。

  • DTDHandler. unparsedEntityDecl(* name ， publicId ， systemId ， ndata *)

    • 处理未解析的实体语句事件。

EntityResolver Objects

  • EntityResolver. resolveEntity(* publicId ， systemId *)
    • 解析实体的系统标识符，然后返回要从中读取的系统标识符作为字符串，或者返回要从中读取的 InputSource。默认实现返回* systemId *。

ErrorHandler Objects

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

  • ErrorHandler. error(* exception *)

    • 在解析器遇到可恢复错误时调用。如果此方法未引发异常，则可以 continue 解析，但是应用程序不应期望进一步的文档信息。允许解析器 continue 进行可能会允许在 Importing 文档中发现其他错误。

  • ErrorHandler. fatalError(* exception *)

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

  • ErrorHandler. warning(* exception *)

    • 在解析器向应用程序显示次要警告信息时调用。当此方法返回时，预计分析将 continue，并且文档信息将 continue 传递给应用程序。在此方法中引发异常将导致解析结束。
Name Python 中文文档
Version
Language
Badge
Last Updated 2021-07-03T12:24:35