xml.dom —文档对象模型 API

源代码： Lib/xml/dom/init.py

---

文档对象模型或“ DOM”是来自 wwwunion(W3C)的一种跨语言 API，用于访问和修改 XML 文档。 DOM 实现将 XML 文档呈现为树结构，或者允许 Client 端代码从头开始构建这种结构。然后，它pass一组对象提供对结构的访问，这些对象提供了众所周知的接口。

DOM 对于随机访问应用程序非常有用。 SAX 一次只允许您查看一份文档。如果您正在查看一个 SAX 元素，则无权访问另一个元素。如果您正在查看文本节点，则无权访问包含元素。编写 SAX 应用程序时，需要在自己的代码中的某个位置跟踪程序在文档中的位置。 SAX 不会为您这样做。另外，如果您需要在 XML 文档中放眼 Future，那您就很不走运。

在无法访问树的事件驱动模型中，某些应用程序根本是不可能的。当然，您可以自己在 SAX 事件中构建某种树，但是 DOM 允许您避免编写该代码。 DOM 是 XML 数据的标准树表示形式。

W3C 正在分阶段定义文档对象模型，或称其术语为“级别”。 API 的 PythonMap 基本上基于 DOM Level 2 建议。

DOM 应用程序通常从将某些 XML 解析为 DOM 开始。 DOM 级别 1 完全没有涵盖如何完成此操作，而 Level 2 仅提供了有限的改进：有一个DOMImplementation对象类，该类提供对Document创建方法的访问，但是无法访问 XML 读取器/解析器/文档构建器。与实现无关的方式。没有现有的Document对象，也没有明确定义的方法来访问这些方法。在 Python 中，每个 DOM 实现都将提供一个函数getDOMImplementation()。 DOM 级别 3 添加了“加载/存储”规范，该规范定义了与阅读器的接口，但是 Python 标准库中尚未提供该接口。

一旦有了 DOM 文档对象，就可以pass其属性和方法访问 XML 文档的各个部分。这些属性在 DOM 规范中定义。参考手册的这一部分描述了 Python 中规范的解释。

W3C 提供的规范定义了 Java，ECMAScript 和 OMG IDL 的 DOM API。此处定义的 PythonMap 在很大程度上基于规范的 IDL 版本，但不需要严格遵守(尽管实现可以自由地支持 IDL 的严格 Map)。有关 Map 要求的详细讨论，请参见Conformance部分。

Module Contents

xml.dom包含以下Function：

• xml.dom. registerDOMImplementation(* name ， factory *)

  • 用名称* name 注册 factory *函数。工厂函数应返回一个实现DOMImplementation接口的对象。根据特定的实现(例如，如果该实现支持某种自定义)，factory 函数可以每次都返回相同的对象，或为每个调用返回一个新对象。

• xml.dom. getDOMImplementation(* name = None ， features =()*)

  • 返回合适的 DOM 实现。 * name *是众所周知的，DOM 实现的模块名称或None。如果不是None，则导入相应的模块，如果导入成功，则返回DOMImplementation对象。如果没有给出名称，并且设置了环境变量 PYTHON_DOM，则使用此变量查找实现。

如果未提供名称，它将检查可用的实现，以找到具有所需Function集的实现。如果找不到实现，请引发ImportError。Function列表必须是(feature, version)对的序列，这些对将被传递到可用DOMImplementation对象上的hasFeature()方法。

还提供了一些方便性常量：

• xml.dom. EMPTY_NAMESPACE

  • 用于指示没有名称空间与 DOM 中的节点关联的值。通常可以将其作为节点的namespaceURI找到，或用作特定于名称空间的方法的* namespaceURI *参数。

• xml.dom. XML_NAMESPACE

  • 与保留前缀xml关联的名称空间 URI，由XML 中的命名空间定义(第 4 节)。

• xml.dom. XMLNS_NAMESPACE

  • 文档对象模型(DOM)2 级核心规范(第 1.1.8 节)定义的名称空间语句的名称空间 URI。

• xml.dom. XHTML_NAMESPACE

  • XHTML 1.0：可扩展的超文本标记语言(第 3.1.1 节)定义的 XHTML 名称空间的 URI。

另外，xml.dom包含基Node类和 DOM 异常类。此模块提供的Node类未实现 DOM 规范定义的任何方法或属性；具体的 DOM 实现必须提供这些实现。作为此模块的一部分提供的Node类的确提供了用于Node具体对象的nodeType属性的常量。它们位于类中而不是模块级别，以符合 DOM 规范。

DOM 中的对象

DOM 的 Authority 文档是 W3C 的 DOM 规范。

请注意，DOM 属性也可以作为节点而不是简单的字符串进行操作。但是，您很少必须执行此操作，因此尚未对此用法进行记录。

另一部分描述了为在 Python 中使用 DOM 定义的异常。

DOMImplementation Objects

DOMImplementation界面为应用程序提供了一种方法来确定其使用的 DOM 中特定Function的可用性。 DOM 2 级增加了使用DOMImplementation创建新的Document和DocumentType对象的Function。

• DOMImplementation. hasFeature(* feature ， version *)

  • 如果实现了由Pair字符串* feature 和 version *标识的Function，则返回True。

• DOMImplementation. createDocument(* namespaceUri ， qualifiedName ， doctype *)

  • 返回一个新的Document对象(DOM 的根)，其子Element对象具有给定的* namespaceUri 和 qualifiedName *。 * doctype *必须是由createDocumentType()或None创建的DocumentType对象。在 Python DOM API 中，前两个参数也可以是None，以指示不会创建Element子级。

• DOMImplementation. createDocumentType(* qualifiedName ， publicId ， systemId *)

  • 返回一个新的DocumentType对象，该对象封装了给定的* qualifiedName ， publicId 和 systemId *字符串，这些字符串表示 XML 文档类型语句中包含的信息。

Node Objects

XML 文档的所有组件都是Node的子类。

• Node. nodeType

  • 表示节点类型的整数。类型的符号常量位于Node对象上：ELEMENT_NODE，ATTRIBUTE_NODE，TEXT_NODE，CDATA_SECTION_NODE，ENTITY_NODE，PROCESSING_INSTRUCTION_NODE，COMMENT_NODE，DOCUMENT_NODE，DOCUMENT_TYPE_NODE，NOTATION_NODE。这是一个只读属性。

• Node. parentNode

  • 当前节点的父级，或文档节点的None。该值始终是Node对象或None。对于Element节点，这将是父元素，但根元素除外，在这种情况下，它将是Document对象。对于Attr个节点，始终为None。这是一个只读属性。

• Node. attributes

  • NamedNodeMap个属性对象。只有元素对此具有实际值；其他人为此属性提供None。这是一个只读属性。

• Node. previousSibling

  • 该节点之前紧跟其后的节点具有相同的父节点。例如，带有结束标签的元素位于* self *元素的开始标签之前。当然，XML 文档不仅由元素组成，所以前一个同级可以是文本，Comments 或其他内容。如果此节点是父节点的第一个孩子，则此属性将为None。这是一个只读属性。

• Node. nextSibling

  • 与该父节点紧随其后的节点。另请参见previousSibling。如果这是 parent 的最后一个孩子，则此属性将为None。这是一个只读属性。

• Node. childNodes

  • 此节点中包含的节点列表。这是一个只读属性。

• Node. firstChild

  • 节点的第一个子节点(如果有)或None。这是一个只读属性。

• Node. lastChild

  • 节点的最后一个子节点(如果有)或None。这是一个只读属性。

• Node. localName

  • 冒号后面的tagName部分(如果有的话)，否则整个tagName。该值是一个字符串。

• Node. prefix

  • tagName冒号前的部分(如果有的话)，否则为空字符串。该值为字符串或None。

• Node. namespaceURI

  • 与元素名称关联的名称空间。这将是一个字符串或None。这是一个只读属性。

• Node. nodeName

  • 对于每种节点类型，这都有不同的含义。有关详细信息，请参见 DOM 规范。您总是可以从另一个属性(例如元素的tagName属性或属性的name属性)获得在此处获得的信息。对于所有节点类型，此属性的值将为字符串或None。这是一个只读属性。

• Node. nodeValue

  • 对于每种节点类型，这都有不同的含义。有关详细信息，请参见 DOM 规范。这种情况类似于nodeName。该值为字符串或None。

• Node. hasAttributes ( )

  • 如果节点具有任何属性，则返回True。

• Node. hasChildNodes ( )

  • 如果该节点有任何子节点，则返回True。

• Node. isSameNode(* other *)

  • 如果* other *指向与此节点相同的节点，则返回True。这对于使用任何类型的代理体系结构的 DOM 实现特别有用(因为一个以上的对象可以引用同一节点)。

• Node. appendChild(* newChild *)

  • 在子节点列表的末尾将此节点添加一个新的子节点，并返回* newChild *。如果该节点已经在树中，则将其首先删除。

• Node. insertBefore(* newChild ， refChild *)

  • 在现有子节点之前插入一个新的子节点。 * refChild *必须是此节点的子级；如果不是，则引发ValueError。 * newChild 返回。如果 refChild 是None，则它将 newChild *插入子级列表的末尾。

• Node. removeChild(* oldChild *)

  • 删除一个子节点。 * oldChild *必须是此节点的子级；如果不是，则引发ValueError。 * oldChild 成功返回。如果 oldChild *不再使用，则应调用其unlink()方法。

• Node. replaceChild(* newChild ， oldChild *)

  • 用新节点替换现有节点。 * oldChild *必须是该节点的子级；如果不是，则引发ValueError。

• Node. normalize ( )

  • 连接相邻的文本节点，以便所有文本段都存储为单个Text实例。这简化了许多应用程序从 DOM 树处理文本的过程。

• Node. cloneNode(深)

  • 克隆此节点。设置* deep *意味着也将克隆所有子节点。这将返回克隆。

NodeList Objects

NodeList代表节点序列。在 DOM Core 建议中，以两种方式使用这些对象：Element对象提供一个作为其子节点列表，而Node的getElementsByTagName()和getElementsByTagNameNS()方法pass此接口返回对象以表示查询结果。

DOM 2 级建议为这些对象定义了一种方法和一种属性：

• NodeList. item(* i *)

  • 返回序列中的第* i 个项(如果有的话)或None。索引 i *不允许小于零或大于或等于序列的长度。

• NodeList. length

  • 序列中的节点数。

另外，Python DOM 接口要求提供一些额外的支持，以允许将NodeList对象用作 Python 序列。所有NodeList实现都必须包括对len()和getitem()的支持；这样可以在for语句中的NodeList上进行迭代，并适当支持len()内置函数。

如果 DOM 实现支持文档的修改，则NodeList实现也必须支持setitem()和delitem()方法。

DocumentType Objects

可以从DocumentType对象获得有关文档语句的符号和实体的信息(如果解析器使用它，并且可以提供信息，则包括外部子集)。文档的DocumentType可从Document对象的doctype属性获得；如果文档没有DOCTYPE语句，则文档的doctype属性将设置为None而不是此接口的实例。

DocumentType是Node的特殊化，并添加了以下属性：

• DocumentType. publicId

  • 文档类型定义的外部子集的公共标识符。这将是一个字符串或None。

• DocumentType. systemId

  • 文档类型定义的外部子集的系统标识符。这将是字符串形式的 URI 或None。

• DocumentType. internalSubset

  • 给出文档完整内部子集的字符串。这不包括包围子集的括号。如果文档没有内部子集，则应为None。

• DocumentType. name

  • DOCTYPE语句中给出的根元素的名称(如果存在)。

• DocumentType. entities

  • 这是一个NamedNodeMap，提供了外部实体的定义。对于多次定义的实体名称，仅提供第一个定义(根据 XML 建议的要求，其他定义将被忽略)。如果解析器未提供信息，或者未定义任何实体，则可能为None。

• DocumentType. notations

  • 这是NamedNodeMap，提供了符号的定义。对于多次定义的 Comments 名称，仅提供第一个定义(其他 Comments 将被 XML 建议所忽略)。如果解析器未提供信息，或者未定义符号，则可能为None。

Document Objects

Document代表整个 XML 文档，包括其组成元素，属性，处理指令，Comments 等。请记住，它继承了Node的属性。

• Document. documentElement

  • 文档的唯一且唯一的根元素。

• Document. createElement(* tagName *)

  • 创建并返回一个新的元素节点。元素在创建时未插入文档中。您需要使用其他方法之一(例如insertBefore()或appendChild())将其显式插入。

• Document. createElementNS(* namespaceURI ， tagName *)

  • 创建并返回带有名称空间的新元素。 * tagName *可以带有前缀。元素在创建时未插入文档中。您需要使用其他方法之一(例如insertBefore()或appendChild())将其显式插入。

• Document. createTextNode(* data *)

  • 创建并返回一个文本节点，其中包含作为参数传递的数据。与其他创建方法一样，该方法不会将节点插入树中。

• Document. createComment(* data *)

  • 创建并返回一个 Comments 节点，其中包含作为参数传递的数据。与其他创建方法一样，该方法不会将节点插入树中。

• Document. createProcessingInstruction(* target ， data *)

  • 创建并返回包含作为参数传递的* target 和 data *的处理指令节点。与其他创建方法一样，该方法不会将节点插入树中。

• Document. createAttribute(* name *)

  • 创建并返回一个属性节点。此方法不将属性节点与任何特定元素关联。您必须在适当的Element对象上使用setAttributeNode()才能使用新创建的属性实例。

• Document. createAttributeNS(* namespaceURI ， qualifiedName *)

  • 创建并返回带有名称空间的属性节点。 * tagName *可以带有前缀。此方法不将属性节点与任何特定元素关联。您必须在适当的Element对象上使用setAttributeNode()才能使用新创建的属性实例。

• Document. getElementsByTagName(* tagName *)

  • 搜索具有特定元素类型名称的所有后代(直系子代，子代子代等)。

• Document. getElementsByTagNameNS(* namespaceURI ， localName *)

  • 搜索具有特定名称空间 URI 和本地名称的所有后代(直系子代，子代子代等)。本地名称是名称空间后面的前缀。

Element Objects

Element是Node的子类，因此继承了该类的所有属性。

• Element. tagName

  • 元素类型名称。在使用命名空间的文档中，它可能包含冒号。该值是一个字符串。

• Element. getElementsByTagName(* tagName *)

  • 与Document类中的等效方法相同。

• Element. getElementsByTagNameNS(* namespaceURI ， localName *)

  • 与Document类中的等效方法相同。

• Element. hasAttribute(* name *)

  • 如果元素具有以* name *命名的属性，则返回True。

• Element. hasAttributeNS(* namespaceURI ， localName *)

  • 如果元素具有以* namespaceURI 和 localName *命名的属性，则返回True。

• Element. getAttribute(* name *)

  • 以字符串形式返回以* name *命名的属性的值。如果不存在这样的属性，则返回一个空字符串，就像该属性没有值一样。

• Element. getAttributeNode(* attrname *)

  • 返回由* attrname *命名的属性的Attr节点。

• Element. getAttributeNS(* namespaceURI ， localName *)

  • 以字符串形式返回以* namespaceURI 和 localName *命名的属性的值。如果不存在这样的属性，则返回一个空字符串，就像该属性没有值一样。

• Element. getAttributeNodeNS(* namespaceURI ， localName *)

  • 给定* namespaceURI 和 localName *，将属性值作为节点返回。

• Element. removeAttribute(* name *)

  • 按名称删除属性。如果没有匹配的属性，则引发NotFoundErr。

• Element. removeAttributeNode(* oldAttr *)

  • 从属性列表中删除并返回* oldAttr (如果存在)。如果 oldAttr *不存在，则引发NotFoundErr。

• Element. removeAttributeNS(* namespaceURI ， localName *)

  • 按名称删除属性。请注意，它使用的是 localName，而不是 qname。如果没有匹配的属性，则不会引发异常。

• Element. setAttribute(* name ， value *)

  • 从字符串设置属性值。

• Element. setAttributeNode(* newAttr *)

  • 将一个新的属性节点添加到该元素，如果name属性匹配，则在必要时替换现有属性。如果发生替换，将返回旧的属性节点。如果* newAttr *已在使用中，将引发InuseAttributeErr。

• Element. setAttributeNodeNS(* newAttr *)

  • 将新的属性节点添加到元素，如果namespaceURI和localName属性匹配，则在必要时替换现有属性。如果发生替换，将返回旧的属性节点。如果* newAttr *已在使用中，将引发InuseAttributeErr。

• Element. setAttributeNS(* namespaceURI ， qname ， value *)

  • 给定* namespaceURI 和 qname *，从字符串设置属性值。请注意，qname 是整个属性名称。这不同于上面。

Attr Objects

Attr继承自Node，因此继承了其所有属性。

• Attr. name

  • 属性名称。在使用名称空间的文档中，它可能包含冒号。

• Attr. localName

  • 如果有一个，则冒号后面的名称部分，否则为整个名称。这是一个只读属性。

• Attr. prefix

  • 如果有一个，则冒号前面的名称部分，否则为空字符串。

• Attr. value

  • 属性的文本值。这是nodeValue属性的同义词。

NamedNodeMap Objects

NamedNodeMap 不是从Node继承。

• NamedNodeMap. length

  • 属性列表的长度。

• NamedNodeMap. item(* index *)

  • 返回具有特定索引的属性。获取属性的 Sequences 是任意的，但在 DOM 的生命周期中将保持一致。每个项目都是一个属性节点。使用value属性获取其值。

也有实验方法使此类具有更多 Map 行为。您可以使用它们，也可以对Element对象使用标准化的getAttribute*()方法族。

Comment Objects

Comment表示 XML 文档中的 Comments。它是Node的子类，但不能有子节点。

• Comment. data
  • Comments 的内容为字符串。该属性包含前<!- -和后- ->之间的所有字符，但不包括它们。

文本和 CDATASection 对象

Text接口表示 XML 文档中的文本。如果解析器和 DOM 实现支持 DOM 的 XML 扩展，则 CDATA 标记的部分中包含的部分文本存储在CDATASection对象中。这两个接口是相同的，但是为nodeType属性提供了不同的值。

这些接口扩展了Node接口。他们不能有子节点。

• Text. data
  • 文本节点的内容为字符串。

ProcessingInstruction Objects

表示 XML 文档中的处理指令；它继承自Node接口，不能有子节点。

• ProcessingInstruction. target

  • 处理指令的内容，直到第一个空白字符。这是一个只读属性。

• ProcessingInstruction. data

  • 第一个空格字符后的处理指令的内容。

Exceptions

DOM Level 2 建议定义了一个异常DOMException，以及多个常量，这些常量使应用程序可以确定发生了哪种错误。 DOMException个实例带有code属性，该属性为特定的异常提供适当的值。

Python DOM 接口提供了常量，但也扩展了异常集，因此 DOM 定义的每个异常代码都存在特定的异常。实现必须引发适当的特定异常，每个异常都带有code属性的适当值。

• exception xml.dom. DOMException

  • 用于所有特定 DOM 异常的基本异常类。此异常类不能直接实例化。

• exception xml.dom. DomstringSizeErr

  • 当指定范围的文本不适合字符串时引发。未知在 Python DOM 实现中会使用此方法，但可能会从非 Python 编写的 DOM 实现中收到此信息。

• exception xml.dom. HierarchyRequestErr

  • 在try插入不允许使用节点类型的节点时引发。

• exception xml.dom. IndexSizeErr

  • 当方法的索引或大小参数为负数或超过允许值时引发。

• exception xml.dom. InuseAttributeErr

  • 在try插入文档中其他位置已经存在的Attr节点时引发。

• exception xml.dom. InvalidAccessErr

  • 在基础对象上不支持参数或操作时引发。

• exception xml.dom. InvalidCharacterErr

  • 当字符串参数包含 XML 1.0 建议中在其上下文中不允许使用的字符时，将引发此异常。例如，try创建元素类型名称中带有空格的Element节点将引发此错误。

• exception xml.dom. InvalidModificationErr

  • 在try修改节点类型时引发。

• exception xml.dom. InvalidStateErr

  • 在try使用未定义或不再可用的对象时引发。

• exception xml.dom. NamespaceErr

  • 如果试图以关于XML 中的命名空间建议的不允许的方式更改任何对象，则会引发此异常。

• exception xml.dom. NotFoundErr

  • 当引用上下文中不存在节点时发生异常。例如，如果传入的节点在 Map 中不存在，则NamedNodeMap.removeNamedItem()将引发此错误。

• exception xml.dom. NotSupportedErr

  • 在实现不支持所请求的对象或操作类型时引发。

• exception xml.dom. NoDataAllowedErr

  • 如果为不支持数据的节点指定了数据，则会引发此问题。

• exception xml.dom. NoModificationAllowedErr

  • 在试图修改不允许修改的对象(例如只读节点)时引发。

• exception xml.dom. SyntaxErr

  • 在指定无效或非法字符串时引发。

• exception xml.dom. WrongDocumentErr

  • 在将节点插入与其当前所属的不同文档中时引发，该实现不支持将该节点从一个文档迁移到另一个文档。

DOM 推荐中定义的异常代码根据此表 Map 到上述异常：

Conformance

本节描述了 Python DOM API，W3C DOM 建议和用于 Python 的 OMG IDLMap 之间的一致性要求和关系。

Type Mapping

根据下表，将 DOM 规范中使用的 IDL 类型 Map 为 Python 类型。

Accessor Methods

从 OMG IDL 到 Python 的 Map 非常像 JavaMap 那样定义 IDL attribute语句的访问器函数。MapIDL 语句

readonly attribute string someValue;
         attribute string anotherValue;

产生三个访问器函数：someValue(_get_someValue())的“ get”方法，anotherValue(_get_anotherValue()和_set_anotherValue())的“ get”和“ set”方法。尤其是，该 Map 不要求 IDL 属性可以像普通 Python 属性一样进行访问：object.someValue是不需要起作用的，并且可以引发AttributeError。

但是，Python DOM API 确实需要正常的属性访问工作。这意味着由 Python IDL 编译器生成的典型代理不太可能起作用，并且如果pass CORBA 访问 DOM 对象，则可能在 Client 端上需要包装对象。尽管这确实需要对 CORBA DOMClient 端进行一些其他考虑，但是具有使用 Python 上的 CORBA 上的 DOM 经验的实现者不会将其视为问题。语句为readonly的属性可能不会限制所有 DOM 实现中的写访问。

在 Python DOM API 中，不需要访问器函数。如果提供的话，它们应该采用 Python IDLMap 定义的形式，但是这些属性被认为是不必要的，因为可以直接从 Python 访问这些属性。切勿为readonly属性提供“设置”访问器。

IDL 定义没有完全体现 W3C DOM API 的要求，例如某些对象的概念，例如getElementsByTagName()的返回值“处于活动状态”。 Python DOM API 不需要实现即可强制执行此类要求。