"xml.dom" --- 文档对象模型 API
******************************

**源代码:** Lib/xml/dom/__init__.py

======================================================================

文档对象模型“DOM”是一个来自万维网联盟（W3C）的跨语言 API，用于访问和修
改 XML 文档。 DOM 的实现将 XML 文档以树结构表示，或者允许客户端代码从
头构建这样的结构。 然后它会通过一组提供通用接口的对象赋予对结构的访问
权。

DOM 特别适用于进行随机访问的应用。 SAX 仅允许你每次查看文档的一小部分
。 如果你正在查看一个 SAX 元素，你将不能访问其他元素。 如果你正在查看
一个文本节点，你将不能访问包含它的元素。 当你编写一个 SAX 应用时，你需
要在你自己的代码的某个地方记住你的程序在文档中的位置。 SAX 不会帮你做
这件事。 并且，如果你想要在 XML 文档中向前查看，你是绝对办不到的。

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

文档对象模型是由 W3C 分阶段定义的，在其术语中称为“层级”。 Python 中该
API 的映射大致是基于 DOM 第 2 层级的建议。

DOM 应用程序通常从将某些 XML 解析为 DOM 开始。 此操作如何实现完全未被
DOM 第 1 层级所涉及，而第 2 层级也只提供了有限的改进：有一个
"DOMImplementation" 对象类，它提供对 "Document" 创建方法的访问，但却没
有办法以不依赖具体实现的方式访问 XML 读取器/解析器/文档创建器。 也没有
当不存在 "Document" 对象的情况下访问这些方法的定义良好的方式。 在
Python 中，每个 DOM 实现将提供一个函数 "getDOMImplementation()"。 DOM
第 3 层级增加了一个载入/存储规格说明，它定义了与读取器的接口，但这在
Python 标准库中尚不可用。

一旦你得到了 DOM 文档对象，你就可以通过 XML 文档的属性和方法访问它的各
个部分。 这些属性定义在 DOM 规格说明当中；参考指南的这一部分描述了
Python 对此规格说明的解读。

W3C 提供的规格说明定义了适用于 Java, ECMAScript 和 OMG IDL 的 DOM API
。 这里定义的 Python 映射很大程度上是基于此规格说明的 IDL 版本，但并不
要求严格映射（但具体实现可以自由地支持对 IDL 的严格映射）。 请参阅 一
致性 一节查看有关映射要求的详细讨论。

参见:

  文档对象模型 (DOM) 第 2 层级规格说明
     被 Python DOM API 作为基础的 W3C 建议。

  文档对象模型 (DOM) 第 1 层级规格说明
     被 "xml.dom.minidom" 所支持的 W3C 针对 DOM 的建议。

  Python 语言映射规格说明
     此文档指明了从 OMG IDL 到 Python 的映射。


模块内容
========

"xml.dom" 包含以下函数:

xml.dom.registerDOMImplementation(name, factory)

   注册 *factory* 函数并使用名称 *name*。 该工厂函数应当返回一个实现了
   "DOMImplementation" 接口的对象。 该工厂函数可每次都返回相同对象，或
   每次调用都返回新的对象，视具体实现的要求而定（例如该实现是否支持某
   些定制功能）。

xml.dom.getDOMImplementation(name=None, features=())

   返回一个合适的 DOM 实现。 *name* 可以是一个知名的名称、某个 DOM 实
   现的模块名或 "None" 。如果不是 "None" ，则导入相应的模块，并在导入
   成功时返回一个 "DOMImplementation" 对象。如果没有给出名称，且设置了
   环境变量 "PYTHON_DOM" ，则会使用该变量来查找实现。标准库中唯一知名
   的名称是针对 "xml.dom.minidom" 的 "'minidom'" 。

   如果没有给出名称，则会检查可用的实现以找到具有所需特性集的实现。如
   果找不到任何实现，则引发 "ImportError" 。特性列表必须是一个由
   "(feature, version)" 对组成的序列，这些对会被传递给可用
   "DOMImplementation" 对象上的 "hasFeature()" 方法。

还提供了一些便捷常量:

xml.dom.EMPTY_NAMESPACE

   用于指示 DOM 中的某个节点没有关联命名空间的值。这通常作为节点的
   "namespaceURI" 出现，或用作特定于命名空间的方法的 *namespaceURI* 形
   参。

xml.dom.XML_NAMESPACE

   关联到保留前缀 "xml" 的命名空间 URI，如 XML 中的命名空间 （第 4 节
   ） 所定义的。

xml.dom.XMLNS_NAMESPACE

   命名空间声明的命名空间 URI，如 文档对象模型 (DOM) 第 2 层级核心规格
   说明 (第 1.1.8节) 所定义的。

xml.dom.XHTML_NAMESPACE

   XHTML 命名空间的 URI，如 XHTML 1.0: 扩展超文本标记语言 (第 3.1.1 节
   ) 所定义的。

In addition, "xml.dom" contains a base "Node" class and the DOM
exception classes.  The "Node" class provided by this module does not
implement any of the methods or attributes defined by the DOM
specification; concrete DOM implementations must provide those.  The
"Node" class provided as part of this module does provide the
constants used for the "nodeType" attribute on concrete "Node"
objects; they are located within the class rather than at the module
level to conform with the DOM specifications.


DOM 中的对象
============

DOM 的权威文档是来自 W3C 的 DOM 规格描述。

本节记录的名称均为 DOM 接口。除 "Node" 和异常类外，它们并非由
"xml.dom" 模块本身提供，而是由具体的 DOM 实现（如 "xml.dom.minidom" ）
提供。

请注意，DOM 属性也可以作为节点而不是简单的字符串进行操作。 然而，必须
这样做的情况相当少见，所以这种用法还没有被写入文档。

+----------------------------------+-------------------------------------+-----------------------------------+
| 接口                             | 小节                                | 目的                              |
|==================================|=====================================|===================================|
| "DOMImplementation"              | DOMImplementation 对象              | 底层实现的接口。                  |
+----------------------------------+-------------------------------------+-----------------------------------+
| "Node"                           | 节点对象                            | 文档中大多数对象的基本接口。      |
+----------------------------------+-------------------------------------+-----------------------------------+
| "NodeList"                       | 节点列表对象                        | 节点序列的接口。                  |
+----------------------------------+-------------------------------------+-----------------------------------+
| "DocumentType"                   | 文档类型对象                        | 有关处理文档所需声明的信息。      |
+----------------------------------+-------------------------------------+-----------------------------------+
| "Document"                       | Document 对象                       | 表示整个文档的对象。              |
+----------------------------------+-------------------------------------+-----------------------------------+
| "Element"                        | 元素对象                            | 文档层次结构中的元素节点。        |
+----------------------------------+-------------------------------------+-----------------------------------+
| "Attr"                           | Attr 对象                           | 元素节点上的属性值节点。          |
+----------------------------------+-------------------------------------+-----------------------------------+
| "Comment"                        | 注释对象                            | 源文档中注释的表示形式。          |
+----------------------------------+-------------------------------------+-----------------------------------+
| "Text"                           | Text 和 CDATASection 对象           | 包含文档中文本内容的节点。        |
+----------------------------------+-------------------------------------+-----------------------------------+
| "ProcessingInstruction"          | ProcessingInstruction 对象          | 处理指令表示形式。                |
+----------------------------------+-------------------------------------+-----------------------------------+

额外的小节描述了在 Python 中使用 DOM 所定义的异常。


DOMImplementation 对象
----------------------

"DOMImplementation" 接口提供了一种让应用程序确定他们所使用的 DOM 中某
一特性可用性的方式。 DOM 第 2 级还添加了使用 "DOMImplementation" 来创
建新的 "Document" 和 "DocumentType" 对象的能力。

DOMImplementation.hasFeature(feature, version)

   如果字符串对 *feature* 和 *version* 所标识的特性已被实现则返回
   "True"。

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

   返回一个新的 "Document" 对象 (DOM 的根节点)，包含一个具有给定
   *namespaceUri* 和 *qualifiedName* 的下级 "Element" 对象。 *doctype*
   必须为由 "createDocumentType()" 创建的 "DocumentType" 对象，或者为
   "None"。 在 Python DOM API 中，前两个参数也可为 "None" 以表示不要创
   建任何下级 "Element"。

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

   返回一个新的封装了给定 *qualifiedName*, *publicId* 和 *systemId* 字
   符串的 "DocumentType" 对象，它表示包含在 XML 文档类型声明中的信息。


节点对象
--------

XML 文档的所有组成部分都是 "Node" 的子类。

只有下列类型的节点才能拥有子节点，且只能是所列类型的子节点：

"Document"
   至多一个 "Element"，至多一个 "DocumentType",
   "ProcessingInstruction" 和 "Comment"

"DocumentFragment" 和 "Element"
   "Element", "Text", "CDATASection", "ProcessingInstruction" 和
   "Comment"

"Attr"
   "Text"

其他类型的节点不能拥有子节点，插入不允许类型的子节点将引发
"HierarchyRequestErr"。

Node.nodeType

   一个代表节点类型的整数。 类型的符号常量在 "Node" 对象上。 这是个只
   读属性。

Node.ELEMENT_NODE
Node.ATTRIBUTE_NODE
Node.TEXT_NODE
Node.CDATA_SECTION_NODE
Node.ENTITY_REFERENCE_NODE
Node.ENTITY_NODE
Node.PROCESSING_INSTRUCTION_NODE
Node.COMMENT_NODE
Node.DOCUMENT_NODE
Node.DOCUMENT_TYPE_NODE
Node.DOCUMENT_FRAGMENT_NODE
Node.NOTATION_NODE

   作为 "nodeType" 属性的可能值的整数常量。

Node.parentNode

   当前节点的上级，或者对于文档节点则为 "None"。 该值总是一个 "Node"
   对象或者 "None"。 对于 "Element" 节点，这将为上级元素，但对于根元素
   例外，在此情况下它将为 "Document" 对象。 对于 "Attr" 节点，它将总是
   为 "None"。 这是个只读属性。

Node.attributes

   属性对象的 "NamedNodeMap"。 这仅对元素才有实际值；其它对象会为该属
   性提供 "None" 值。 这是个只读属性。

Node.previousSibling

   在此节点之前具有相同上级的相邻节点。 例如结束标记紧接在 *self* 元素
   的开始标记之前的元素。 当然，XML 文档并非只是由元素组成，因此之前相
   邻节点可以是文本、注释或者其他内容。 如果此节点是上级的第一个子节点
   ，则该属性将为 "None"。 这是一个只读属性。

Node.nextSibling

   在此节点之后具有相同上级的相邻节点。 另请参见 "previousSibling"。
   如果此节点是上级的最后一个子节点，则该属性将为 "None"。 这是一个只
   读属性。

Node.childNodes

   由该节点的子节点组成的 "NodeList"。 如果节点没有子节点，则该列表为
   空。 这是个只读属性。

Node.firstChild

   节点的第一个下级，如果有的话，否则为 "None"。 这是个只读属性。

Node.lastChild

   节点的最后一个下级，如果有的话，否则为 "None"。 这是个只读属性。

Node.localName

   "tagName" 中冒号后面的部分（如果存在），否则为整个 "tagName" 。该值
   为字符串。

Node.prefix

   "tagName" 中冒号前面的部分（如果存在），否则为空字符串。该值为字符
   串或 "None" 。

Node.namespaceURI

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

Node.ownerDocument

   该节点所属的 "Document" 对象，如果该节点本身是文档则为 "None" 。这
   是一个只读属性。

Node.isSupported(feature, version)

   返回 DOM 实现是否支持特定的 *feature* ，就像
   "DOMImplementation.hasFeature()" 所做的那样。

Node.setUserData(key, data, handler)

   将 *data* 与该节点上的 *key* 关联，并返回先前与 *key* 关联的数据，
   如果没有则返回 "None" 。如果 *data* 为 "None" ，则移除该关联。当节
   点被克隆、导入、重命名或删除时，将调用 *handler* ；如果不需要通知，
   请传入 "None" 。

Node.getUserData(key)

   返回通过 "setUserData()" 与该节点上的 *key* 相关联的数据，如果没有
   则返回 "None" 。

Node.nodeName

   该节点的名称，取决于其类型；参见下表。你始终可以从另一个属性中获取
   此处能获取的信息，例如元素的 "tagName" 属性或特性的 "name" 属性。这
   是一个只读属性。

Node.nodeValue

   该节点的值，取决于其类型；参见下表。该值为字符串或 "None" 。

每种节点类型的 "nodeName" 和 "nodeValue" 的值如下：

+----------------------------------+-----------------------------------------+---------------------------------------+
| 节点类型                         | nodeName                                | nodeValue                             |
|==================================|=========================================|=======================================|
| "Attr"                           | "name"                                  | "value"                               |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "CDATASection"                   | "'#cdata-section'"                      | 内容                                  |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "Comment"                        | "'#comment'"                            | 内容                                  |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "Document"                       | "'#document'"                           | "None"                                |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "DocumentFragment"               | "'#document-fragment'"                  | "None"                                |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "DocumentType"                   | "name"                                  | "None"                                |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "Element"                        | "tagName"                               | "None"                                |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "Entity"                         | 实体名称                                | "None"                                |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "Notation"                       | 标注名称                                | "None"                                |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "ProcessingInstruction"          | "target"                                | "data"                                |
+----------------------------------+-----------------------------------------+---------------------------------------+
| "Text"                           | "'#text'"                               | 内容                                  |
+----------------------------------+-----------------------------------------+---------------------------------------+

Node.hasAttributes()

   如果该节点具有任何属性则返回 "True"。

Node.hasChildNodes()

   如果该节点具有任何子节点则返回 "True"。

Node.isSameNode(other)

   如果 *other* 指向的节点就是此节点则返回 "True"。 这对于使用了任何代
   理架构的 DOM 实现来说特别有用（因为多个对象可能指向相同节点）。

   备注:

     这是基于已提议的 DOM 第 3 层级 API，目前尚处于“起草”阶段，但这个
     特定接口看来并不存在争议。 来自 W3C 的修改将不会影响 Python DOM
     接口中的这个方法（不过针对它的任何新 W3C API 也将受到支持）。

Node.appendChild(newChild)

   在子节点列表末尾添加一个新的子节点，返回 *newChild*。 如果节点已存
   在于树结构中，它将先被移除。

Node.insertBefore(newChild, refChild)

   在现有的子节点之前插入一个新的子节点。 *refChild* 必须是该节点的子
   节点；如果不是，则引发 "NotFoundErr" 。返回 *newChild* 。如果
   *refChild* 为 "None" ，则将 *newChild* 插入到子节点列表的末尾。

Node.removeChild(oldChild)

   移除一个子节点。 *oldChild* 必须是该节点的子节点；如果不是，则引发
   "NotFoundErr" 。成功时返回 *oldChild* 。如果不再使用 *oldChild* ，
   则应调用其 "unlink()" 方法。

Node.replaceChild(newChild, oldChild)

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

Node.normalize()

   合并相邻的文本节点以便将所有文本段存储为单个 "Text" 实例。 这可以简
   化许多应用程序处理来自 DOM 树文本的操作。

Node.cloneNode(deep)

   克隆此节点。 设置 *deep* 表示也克隆所有子节点。 此方法将返回克隆的
   节点。


节点列表对象
------------

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

"NodeList" *不* 继承自 "Node" 。

DOM 第 2 层级建议为这些对象定义一个方法和一个属性:

NodeList.item(i)

   返回序列中的第 *i* 项，如果 *i* 超出范围则返回 "None" 。不支持负索
   引。

NodeList.length

   序列中的节点数量。

此外，Python DOM 接口还要求提供一些额外支持来允许将 "NodeList" 对象用
作 Python 序列。 所有 "NodeList" 实现都必须包括对 "__len__()" 和
"__getitem__()" 的支持；这样 "NodeList" 就允许使用 "for" 语句进行迭代
并能正确地支持 "len()" 内置函数。

如果一个 DOM 实现支持文档的修改，则 "NodeList" 实现还必须支持
"__setitem__()" 和 "__delitem__()" 方法。


文档类型对象
------------

关于文档声明的记号和实体的信息（包括外部子集，如果解析器使用了它并且能
够提供该信息）可从 "DocumentType" 对象获取。文档的 "DocumentType" 可从
"Document" 对象的 "doctype" 属性获取；如果文档没有 "DOCTYPE" 声明，则
该文档的 "doctype" 属性将被设置为 "None" 而不是此接口的实例。

"DocumentType" 是 "Node" 的专门化，并增加了下列属性:

DocumentType.publicId

   文档类型定义外部子集的公共标识符，如果 "DOCTYPE" 声明未指定它则为
   "None" 。

DocumentType.systemId

   文档类型定义外部子集的系统标识符（URI），如果 "DOCTYPE" 声明未指定
   它则为 "None" 。

DocumentType.internalSubset

   一个给出来自文档的完整内部子集的字符串。 这不包括子集外面的方括号。
   如果文档没有内部子集，则应为 "None"。

DocumentType.name

   "DOCTYPE" 声明中给出的根元素名称，如果有的话。

DocumentType.entities

   这是一个由给出外部实体定义的 "Entity" 节点组成的 "NamedNodeMap" 。
   对于多次定义的实体名称，仅提供第一个定义（按 XML 建议的要求忽略其他
   定义）。如果解析器未提供该信息，或者没有定义任何实体，则可能为
   "None" 。

DocumentType.notations

   这是一个由给出记号定义的 "Notation" 节点组成的 "NamedNodeMap" 。对
   于多次定义的记号名称，仅提供第一个定义（按 XML 建议的要求忽略其他定
   义）。如果解析器未提供该信息，或者没有定义任何记号，则可能为 "None"
   。


Document 对象
-------------

"Document" 代表一个完整的 XML 文档，包括其组成元素、属性、处理指令和注
释等。 请记住它会继承来自 "Node" 的属性。

Document.documentElement

   文档唯一的根元素。

Document.doctype

   文档的 "DocumentType" 节点，如果没有则为 "None" 。这是一个只读属性
   。

Document.implementation

   创建此文档的 "DOMImplementation" 对象。这是一个只读属性。

Document.strictErrorChecking

   是否强制执行错误检查。

Document.documentURI

   文档的位置，如果未知则为 "None" 。

Document.createDocumentFragment()

   创建并返回一个空的 "DocumentFragment" 节点。

Document.createCDATASection(data)

   创建并返回一个包含 *data* 的 "CDATASection" 节点。

Document.importNode(importedNode, deep)

   返回属于此文档的 *importedNode* 的副本。原始节点不会从其文档中移除
   。如果 *deep* 为真，该节点的后代节点也会被复制。

Document.createElement(tagName)

   创建并返回一个新的元素节点。元素在创建时不会插入到文档中。你需要使
   用其他方法（例如 "insertBefore()" 或 "appendChild()" ）显式插入它。

Document.createElementNS(namespaceURI, tagName)

   创建并返回一个带命名空间的新元素。 *tagName* 可以包含前缀。元素在创
   建时不会插入到文档中。你需要使用其他方法（例如 "insertBefore()" 或
   "appendChild()" ）显式插入它。

Document.createTextNode(data)

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

Document.createComment(data)

   创建并返回一个包含作为形参被传入的数据的注释节点。 与其他创建方法一
   样，此方法不会将节点插入到树中。

Document.createProcessingInstruction(target, data)

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

Document.createAttribute(name)

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

Document.createAttributeNS(namespaceURI, qualifiedName)

   创建并返回一个带命名空间的属性节点。 *tagName* 可以包含前缀。此方法
   不会将属性节点与任何特定元素相关联。你必须在适当的 "Element" 对象上
   使用 "setAttributeNode()" 来使用新创建的属性实例。

Document.getElementById(id)

   返回具有给定 ID 的元素，如果没有则返回 "None" 。仅搜索在 DTD 中或由
   "Element.setIdAttribute()" 声明为 ID 类型的属性。

Document.getElementsByTagName(tagName)

   搜索全部具有特定元素类型名称的后继元素（直接下级、下级的下级等等）
   。

Document.getElementsByTagNameNS(namespaceURI, localName)

   搜索全部具有特定命名空间 URI 和 localname 的后继元素（直接下级、下
   级的下级等等）。 localname 是命名空间在前缀之后的部分。

Document.renameNode(n, namespaceURI, name)

   重命名元素或属性节点 *n* 并将其返回。 *namespaceURI* 是新的命名空间
   URI，如果该节点不属于命名空间则为 "EMPTY_NAMESPACE" 。 *name* 是新
   的限定名称。

   如果 *n* 是由另一个文档创建的，则引发 "WrongDocumentErr" ；如果它既
   不是元素也不是属性，则引发 "NotSupportedErr" 。


元素对象
--------

"Element" 是 "Node" 的子类，因此会继承该类的全部属性。

Element.tagName

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

Element.setIdAttribute(name)

   声明属性 *name* 为 ID 类型，以便通过 "Document.getElementById()" 找
   到该元素。如果元素没有此类属性，则引发 "NotFoundErr" 。

Element.setIdAttributeNS(namespaceURI, localName)

   与 "setIdAttribute()" 相同，但用于由命名空间 URI 和本地名称指定的属
   性。

Element.setIdAttributeNode(idAttr)

   与 "setIdAttribute()" 相同，但用于已经检索到的属性节点。

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)

   按名称移除属性。

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 对象
---------

"Attr" 继承自 "Node"，因此会继承其全部属性。

属性节点不属于文档树的一部分。它们包含在元素的 "attributes" 映射中，而
不是在其子节点中，并且它们的 "parentNode" 、 "previousSibling" 和
"nextSibling" 始终为 "None" 。

Attr.name

   属性名称。 在使用命名空间的文档中可能会包括冒号。

Attr.localName

   名称在冒号之后的部分，如果有的话，否则为完整名称。 这是个只读属性。

Attr.prefix

   名称在冒号之前的部分，如果有冒号的话，否则为空字符串。

Attr.isId

   该属性是否为 ID 类型，无论是因为在 DTD 中如此声明还是因为使用了
   "Element.setIdAttribute()" 。这是一个只读属性。

Attr.ownerElement

   该属性所属的 "Element" 节点，如果未使用则为 "None" 。这是一个只读属
   性。

Attr.specified

   该属性的值是否在文档中显式设置，而不是从 DTD 继承默认值。这是一个只
   读属性。

Attr.value

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


NamedNodeMap 对象
-----------------

"NamedNodeMap" *不是* 继承自 "Node"。

NamedNodeMap.length

   属性列表的长度。

NamedNodeMap.item(index)

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

NamedNodeMap.getNamedItem(name)

   返回具有给定 "name" 的节点，如果没有此类节点则返回 "None" 。

NamedNodeMap.getNamedItemNS(namespaceURI, localName)

   返回具有给定命名空间 URI 和本地名称的节点，如果没有此类节点则返回
   "None" 。

NamedNodeMap.setNamedItem(node)

   将 *node* 添加到映射中，使用其 "name" 作为键。返回被其替换的节点，
   如果未替换任何节点则返回 "None" 。

NamedNodeMap.setNamedItemNS(node)

   将 *node* 添加到映射中，使用其命名空间 URI 和本地名称作为键。返回被
   其替换的节点，如果未替换任何节点则返回 "None" 。

NamedNodeMap.removeNamedItem(name)

   移除并返回具有给定 "name" 的节点。如果没有此类节点，则引发
   "NotFoundErr" 。

NamedNodeMap.removeNamedItemNS(namespaceURI, localName)

   移除并返回具有给定命名空间 URI 和本地名称的节点。如果没有此类节点，
   则引发 "NotFoundErr" 。

你也可以在 "Element" 对象上使用标准化的 "getAttribute*()" 系列方法。


DocumentFragment 对象
---------------------

"DocumentFragment" 是节点的轻量级容器。它是 "Node" 的子类。当它被插入
到文档树中时，会插入它的子节点而不是它本身，并且它变为空。


CharacterData 对象
------------------

"CharacterData" 表示 XML 文档中类似文本的数据。它是 "Node" 的子类，也
是 "Text" 、 "CDATASection" 和 "Comment" 的基类。此类节点不能拥有子节
点。

CharacterData.data

   以字符串形式呈现的节点内容。

CharacterData.length

   "data" 中的字符数。这是一个只读属性。

CharacterData.substringData(offset, count)

   返回 "data" 从 *offset* 开始、长度为 *count* 个字符的子字符串。

CharacterData.appendData(arg)

   将字符串 *arg* 追加到 "data" 。

CharacterData.insertData(offset, arg)

   在 *offset* 处将字符串 *arg* 插入到 "data" 中。

CharacterData.deleteData(offset, count)

   从 *offset* 开始，从 "data" 中移除 *count* 个字符。

CharacterData.replaceData(offset, count, arg)

   从 *offset* 开始，用字符串 *arg* 替换 "data" 中的 *count* 个字符。


注释对象
--------

"Comment" 表示 XML 文档中的注释。它是 "CharacterData" 的子类。

Comment.data

   注释的内容是一个字符串。 该属性包含在开头 "<!-""-" 和末尾 "-""->"
   之间的所有字符，但不包括这两个符号。


Text 和 CDATASection 对象
-------------------------

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

"Text" 继承 "CharacterData" 接口，而 "CDATASection" 继承 "Text" 。

Text.data

   字符串形式的文本节点内容。

Text.wholeText

   按文档顺序连接的所有在逻辑上与该节点相邻的 "Text" 节点的文本。这是
   一个只读属性。

Text.replaceWholeText(content)

   将所有在逻辑上与该节点相邻的 "Text" 节点的文本替换为 *content* ，并
   移除其他节点。返回该节点，如果 *content* 为空则返回 "None" 。

Text.splitText(offset)

   在 *offset* 处将该节点拆分为两个节点，将第一部分保留在该节点中，并
   返回包含其余部分的新兄弟节点。

备注:

  "CDATASection" 节点的使用并不表示该节点代表一个完整的 CDATA 标记节，
  只是表示该节点的内容是 CDATA 节的一部分。 单个 CDATA 节可以由文档树
  中的多个节点来表示。 没有什么办法能确定两个相邻的 "CDATASection" 节
  点是否代表不同的 CDATA 标记节。


ProcessingInstruction 对象
--------------------------

代表 XML 文档中的处理指令。 它继承自 "Node" 接口并且不能拥有下级节点。

ProcessingInstruction.target

   到第一个空格符为止的处理指令内容。 这是个只读属性。

ProcessingInstruction.data

   在第一个空格符之后的处理指令内容。


Entity 对象
-----------

"Entity" 表示在 DTD 中声明的已解析或未解析实体。它是 "Node" 的子类。
Entity 节点包含在 "DocumentType.entities" 中，不能插入到文档树中。实体
的名称是其 "nodeName" 。

Entity.publicId

   实体的公共标识符，如果未指定则为 "None" 。这是一个只读属性。

Entity.systemId

   实体的系统标识符，如果未指定则为 "None" 。这是一个只读属性。

Entity.notationName

   未解析实体的记号名称，对于已解析实体则为 "None" 。这是一个只读属性
   。


Notation 对象
-------------

"Notation" 表示在 DTD 中声明的记号。它是 "Node" 的子类，不能拥有子节点
。Notation 节点包含在 "DocumentType.notations" 中，不能插入到文档树中
。记号的名称是其 "nodeName" 。

Notation.publicId

   记号的公共标识符，如果未指定则为 "None" 。这是一个只读属性。

Notation.systemId

   记号的系统标识符，如果未指定则为 "None" 。这是一个只读属性。


异常
----

DOM 第 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

   当尝试插入一个节点但该节点类型不被允许时被引发。

exception xml.dom.IndexSizeErr

   当一个方法的索引或大小参数为负值或超出允许的值范围时被引发。

exception xml.dom.InuseAttributeErr

   当尝试插入一个 "Attr" 节点但该节点已存在于文档中的某处时被引发。

exception xml.dom.InvalidAccessErr

   当某个参数或操作在底层对象中不受支持时被引发。

exception xml.dom.InvalidCharacterErr

   当某个字符串参数包含的字符在使用它的上下文中不被 XML 1.0 标准建议所
   允许时引发。 例如，尝试创建一个元素类型名称中带有空格的 "Element"
   节点将导致此错误被引发。

exception xml.dom.InvalidModificationErr

   当尝试修改某个节点的类型时被引发。

exception xml.dom.InvalidStateErr

   当尝试使用未定义或不再可用的对象时被引发。

exception xml.dom.NamespaceErr

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

exception xml.dom.NotFoundErr

   当某个节点不存在于被引用的上下文中时引发的异常。 例如，
   "NamedNodeMap.removeNamedItem()" 将在所传入的节点不存在于映射中时引
   发此异常。

exception xml.dom.NotSupportedErr

   当具体实现不支持所请求的对象类型或操作时被引发。

exception xml.dom.NoDataAllowedErr

   当为某个不支持数据的节点指定数据时被引发。

exception xml.dom.NoModificationAllowedErr

   当尝试修改某个不允许修改的对象（例如只读节点）时被引发。

exception xml.dom.SyntaxErr

   当指定了无效或非法的字符串时被引发。

exception xml.dom.ValidationErr

   当某项操作会使文档在部分有效性方面变为无效时引发。已知在 Python DOM
   实现中没有使用此异常，但可能会从非 Python 编写的 DOM 实现中接收到它
   。

exception xml.dom.WrongDocumentErr

   当将某个节点插入非其当前所属的另一个文档，并且具体实现不支持从一个
   文档向另一个文档迁移节点时被引发。

DOM 建议映射中针对上述异常而定义的异常代码如下表所示:

+-----------------------------------------+-----------------------------------+
| 常量                                    | 异常                              |
|=========================================|===================================|
| xml.dom.DOMSTRING_SIZE_ERR              | "DomstringSizeErr"                |
+-----------------------------------------+-----------------------------------+
| xml.dom.HIERARCHY_REQUEST_ERR           | "HierarchyRequestErr"             |
+-----------------------------------------+-----------------------------------+
| xml.dom.INDEX_SIZE_ERR                  | "IndexSizeErr"                    |
+-----------------------------------------+-----------------------------------+
| xml.dom.INUSE_ATTRIBUTE_ERR             | "InuseAttributeErr"               |
+-----------------------------------------+-----------------------------------+
| xml.dom.INVALID_ACCESS_ERR              | "InvalidAccessErr"                |
+-----------------------------------------+-----------------------------------+
| xml.dom.INVALID_CHARACTER_ERR           | "InvalidCharacterErr"             |
+-----------------------------------------+-----------------------------------+
| xml.dom.INVALID_MODIFICATION_ERR        | "InvalidModificationErr"          |
+-----------------------------------------+-----------------------------------+
| xml.dom.INVALID_STATE_ERR               | "InvalidStateErr"                 |
+-----------------------------------------+-----------------------------------+
| xml.dom.NAMESPACE_ERR                   | "NamespaceErr"                    |
+-----------------------------------------+-----------------------------------+
| xml.dom.NOT_FOUND_ERR                   | "NotFoundErr"                     |
+-----------------------------------------+-----------------------------------+
| xml.dom.NOT_SUPPORTED_ERR               | "NotSupportedErr"                 |
+-----------------------------------------+-----------------------------------+
| xml.dom.NO_DATA_ALLOWED_ERR             | "NoDataAllowedErr"                |
+-----------------------------------------+-----------------------------------+
| xml.dom.NO_MODIFICATION_ALLOWED_ERR     | "NoModificationAllowedErr"        |
+-----------------------------------------+-----------------------------------+
| xml.dom.SYNTAX_ERR                      | "SyntaxErr"                       |
+-----------------------------------------+-----------------------------------+
| xml.dom.VALIDATION_ERR                  | "ValidationErr"                   |
+-----------------------------------------+-----------------------------------+
| xml.dom.WRONG_DOCUMENT_ERR              | "WrongDocumentErr"                |
+-----------------------------------------+-----------------------------------+


一致性
======

本节描述了 Python DOM API、W3C DOM 建议以及 Python 的 OMG IDL 映射之间
的一致性要求和关系。


类型映射
--------

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

+--------------------+---------------------------------------------+
| IDL 类型           | Python 类型                                 |
|====================|=============================================|
| "boolean"          | "bool" 或 "int"                             |
+--------------------+---------------------------------------------+
| "int"              | "int"                                       |
+--------------------+---------------------------------------------+
| "long int"         | "int"                                       |
+--------------------+---------------------------------------------+
| "unsigned int"     | "int"                                       |
+--------------------+---------------------------------------------+
| "DOMString"        | "str" 或 "bytes"                            |
+--------------------+---------------------------------------------+
| "null"             | "None"                                      |
+--------------------+---------------------------------------------+


访问器方法
----------

从 OMG IDL 到 Python 的映射以类似于 Java 映射的方式定义了针对 IDL
"attribute" 声明的访问器函数。 映射以下 IDL 声明

   readonly attribute string someValue;
            attribute string anotherValue;

产生三个访问器函数： "someValue" 的 "get" 方法（ "_get_someValue()" ）
，以及 "anotherValue" 的 "get" 和 "set" 方法（ "_get_anotherValue()"
和 "_set_anotherValue()" ）。特别地，该映射并不要求像普通 Python 属性
那样可以访问 IDL 属性： "object.someValue" *不* 要求必须有效，并且可能
会引发 "AttributeError" 。

但是，Python DOM API 则 *确实* 要求普通属性访问可用。 这意味着由
Python IDL 解译器生成的典型代理有可能会不可用，如果 DOM 对象是通过
CORBA 来访问则在客户端可能需要有包装对象。 虽然这确实要求为 CORBA DOM
客户端进行额外的考虑，但具有从 Python 通过 CORBA 使用 DOM 经验的实现并
不会认为这是个问题。 已经声明了 "readonly" 的属性不必在所有 DOM 实现中
限制写入访问。

在 Python DOM API 中，访问器函数不是必须的。 如果提供，则它们应当采用
由 Python IDL 映射所定义的形式，但这些方法会被认为不必要，因为这些属性
可以从 Python 直接访问。 永远都不要为 "readonly" 属性提供 "set" 访问器
。

IDL 定义并未完全体现 W3C DOM API 的要求，例如某些对象（例如
"getElementsByTagName()" 的返回值）是“动态的” (live) 这一概念。Python
DOM API 并不要求实现强制执行此类要求。
