xml.dom

xml.dom - 文档对象模型API

2.0版本中的新功能。

文档对象模型或“DOM”是万维网联盟（W3C）的跨语言API，用于访问和修改XML文档。DOM实现将XML文档呈现为树结构，或者允许客户端代码从头构建这样的结构。然后通过提供众所周知的接口的一组对象来访问该结构。

DOM对随机访问应用程序非常有用。SAX只允许您一次查看文档的一个位。如果您正在查看一个SAX元素，则无法访问其他元素。如果您正在查看文本节点，则无法访问包含元素。当你编写一个SAX应用程序时，你需要跟踪自己代码中某个地方的程序在文档中的位置。SAX不会为你做。另外，如果你需要在XML文档中向前看，你只是运气不好。

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

文档对象模型由W3C分阶段定义，或者在其术语中定义为“级别”。API的Python映射基本上基于DOM Level 2推荐。

通常，DOM应用程序首先将一些XML解析为DOM。 如何实现这一点完全没有被DOM Level 1覆盖，而Level 2只提供了有限的改进：有一个DOMImplementation对象类，它提供了对文档创建方法的访问，但没有办法访问XML读取器/解析器/文档构建器 独立于实现的方式。 在没有现有Document对象的情况下，也没有明确定义的方式来访问这些方法。 在Python中，每个DOM实现将提供一个函数getDOMImplementation（）。 DOM Level 3添加了一个Load / Store规范，该规范为读者定义了一个接口，但是这在Python标准库中尚不可用。

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

W3C提供的规范定义了用于Java，ECMAScript和OMG IDL的DOM API。这里定义的Python映射很大程度上基于IDL版本的规范，但不需要严格的遵从（尽管实现可以自由支持来自IDL的严格映射）。有关映射要求的详细讨论，请参阅一致性部分。

扩展内容

文档对象模型（DOM）Level 2规范 Python DOM API所基于的W3C推荐标准。文档对象模型（DOM）1级规范 W3C推荐的DOM支持xml.dom.minidom。Python语言映射规范这指定了从OMG IDL到Python的映射。

1.模块内容

将xml.dom包含以下功能：

xml.dom.registerDOMImplementation(name, factory)

注册工厂名称为功能名称。工厂函数应该返回一个实现DOMImplementation接口的对象。工厂函数可以每次都返回相同的对象，或者针对每次调用返回一个新对象，以适合特定的实现（例如，如果该实现支持一些定制）。

xml.dom.getDOMImplementation([name[, features]])

返回一个合适的DOM实现。 该名称是众所周知的，DOM实现的模块名称或None。 如果不是None，则导入相应的模块，并在导入成功时返回DOMImplementation对象。 如果未给出名称，并且已设置环境变量PYTHON_DOM，则使用此变量查找实现。

如果没有给出名称，这将检查可用实现以找到具有所需功能集的实现。如果没有找到实现，请举一个ImportError。(feature, version)要素列表必须是hasFeature()在可用DOMImplementation对象上传递给方法的一系列对。

还提供了一些便利常数：

xml.dom.EMPTY_NAMESPACE

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

2.2版本中的新功能。

xml.dom.XML_NAMESPACE

与保留前缀关联的名称空间URI xml，由XML中的Namespaces定义（第4节）。

2.2版本中的新功能。

xml.dom.XMLNS_NAMESPACE

由文档对象模型（DOM）Level 2 Core Specification（第1.1.8节）定义的名称空间声明的名称空间URI 。

2.2版本中的新功能。

xml.dom.XHTML_NAMESPACE

由XHTML 1.0定义的XHTML名称空间的URI ：可扩展超文本标记语言（3.1.1节）。

2.2版本中的新功能。

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

2. DOM中的对象

DOM的权威性文档是W3C的DOM规范。

请注意，DOM属性也可以作为节点来操作，而不是简单的字符串。然而，你必须这样做是非常罕见的，所以这种用法还没有记录。

附加部分描述了在Python中使用DOM定义的异常。

2.1。DOMImplementation对象

DOMImplementation接口为应用程序提供了一种方法来确定他们正在使用的DOM中特定功能的可用性。 DOM Level 2增加了使用DOMImplementation创建新的Document和DocumentType对象的功能。

DOMImplementation.hasFeature(feature, version)

如果实现了一对字符串功能和版本标识的功能，则返回true 。

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

使用具有给定namespaceUri和qualifiedName的子元素对象返回一个新的Document对象（DOM的根）。 doctype必须是由createDocumentType（）或None创建的DocumentType对象。 在Python DOM API中，前两个参数也可以是None，以表示不要创建Element子元素。

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

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

2.2 节点对象

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。 对于元素节点，这将是父元素，除了根元素，在这种情况下它将是Document对象。 对于Attr节点，这总是无。 这是一个只读属性。

Node.attributes

一个NamedNodeMap属性对象。只有元素才具有实际的价值; 其他人提供None这个属性。这是一个只读属性。

Node.previousSibling

紧跟在同一父节点之前的节点。例如，在自身元素的开始标记之前有一个结束标记的元素。当然，XML文档不仅仅包含元素，所以以前的兄弟可以是文本，评论或其他东西。如果此节点是父项的第一个子项，则此属性将为None。这是一个只读属性。

Node.nextSibling

紧跟在这个父节点之后的节点。另见previousSibling。如果这是父项的最后一个子项，则此属性将为None。这是一个只读属性。

Node.childNodes

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

Node.firstChild

节点的第一个孩子，如果有的话，或者None。这是一个只读属性。

Node.lastChild

节点的最后一个子节点，如果有的话，或者None。这是一个只读属性。

Node.localName

如果有冒号，冒号后面的部分是冒号，否则整个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实现特别有用（因为多个对象可以引用同一个节点）。

注意

这是基于建议的DOM Level 3 API，它仍处于“工作草案”阶段，但这个特定的界面似乎没有争议。来自W3C的改变不一定会影响Python DOM接口中的这​​种方法（尽管任何新的W3C API也会被支持）。

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树处理文本。

2.1版本中的新功能。

Node.cloneNode(deep)

克隆这个节点。设置deep 意味着克隆所有子节点。这将返回克隆。

2.3 NodeList对象

NodeList表示一系列节点。 这些对象在DOM核心推荐中以两种方式使用：一个Element对象提供一个作为其子节点列表，Node的getElementsByTagName（）和getElementsByTagNameNS（）方法返回具有此接口的对象以表示查询结果。

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

NodeList.item(i)

如果还有一个，则返回序列中的第i 项None。指数i 不得小于零或大于或等于序列的长度。

NodeList.length

序列中的节点数量。

另外，Python DOM接口要求提供一些额外的支持，以允许NodeList对象用作Python序列。 所有的NodeList实现都必须包含对__len __（）和__getitem __（）的支持; 这允许迭代NodeList中的for语句并正确支持len（）内置函数。

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

2.4 DocumentType对象

有关由文档声明的符号和实体的信息（包括解析器使用它并可以提供信息的外部子集）可从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，给出了符号的定义。 对于不止一次定义的记法名称，只提供第一个定义（其他则根据XML建议的要求而被忽略）。 如果信息不是由解析器提供的，或者没有定义符号，则这可能是None。

2.5 文档对象

Document表示整个XML文档，包括其组成元素，属性，处理指令，注释等。请记住它从中继承属性Node。

Document.documentElement

文档的唯一根元素。

Document.createElement(tagName)

创建并返回一个新的元素节点。 元素在创建时未插入到文档中。 您需要使用其他方法之一（如insertBefore（）或appendChild（））来显式插入它。

Document.createElementNS(namespaceURI, tagName)

用命名空间创建并返回一个新元素。 tagName可能有一个前缀。 元素在创建时未插入到文档中。 您需要使用其他方法之一（如insertBefore（）或appendChild（））来显式插入它。

Document.createTextNode(data)

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

Document.createComment(data)

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

Document.createProcessingInstruction(target, data)

创建并返回包含作为参数传递的目标和数据的处理指令节点。与其他创建方法一样，这个方法不会将节点插入树中。

Document.createAttribute(name)

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

Document.createAttributeNS(namespaceURI, qualifiedName)

用命名空间创建并返回一个属性节点。 tagName可能有一个前缀。 此方法不会将属性节点与任何特定元素相关联。 您必须在适当的Element对象上使用setAttributeNode（）来使用新创建的属性实例。

Document.getElementsByTagName(tagName)

搜索所有具有特定元素类型名称的后代（直接子代，子代孩子等）。

Document.getElementsByTagNameNS(namespaceURI, localName)

使用特定的命名空间URI和本地名搜索所有后代（直接的子节点，子节点的子节点等）。localname是前缀后的名称空间的一部分。

2.6 元素对象

Element是node的一个子类，所以继承了该类的所有属性。

Element.tagName

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

Element.getElementsByTagName(tagName)

与Document类中的等同方法类似。

Element.getElementsByTagNameNS(namespaceURI, localName)

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

Element.hasAttribute(name)

如果元素具有按名称 命名的属性，则返回true 。

Element.hasAttributeNS(namespaceURI, localName)

如果元素具有由namespaceURI和localName命名的属性，则返回true 。

Element.getAttribute(name)

以字符串形式返回按名称 命名的属性的值。如果不存在这样的属性，则返回空字符串，就好像该属性没有值。

Element.getAttributeNode(attrname)

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

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是整个属性名称。这与以上不同。

2.7 属性对象

Attr从Node中继承，所以继承了它的所有属性。

Attr.name

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

Attr.localName

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

Attr.prefix

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

Attr.value

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

2.8 命名的节点映射对象

NamedNodeMap并没有继承Node。

NamedNodeMap.length

属性列表的长度。

NamedNodeMap.item(index)

返回具有特定索引的属性。您获取属性的顺序是任意的，但对于DOM的生命周期将保持一致。每个项目是一个属性节点。通过value属性获取它的值。

也有实验方法给这个类更多的映射行为。您可以使用它们，也可以getAttribute*()在Element对象上使用标准化的方法族。

2.9 评论对象

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

Comment.data

评论的内容为一个字符串。该属性包含前导<!--和尾随之间的所有字符-->，但不包括它们。

2.10。文本和CDATASection对象

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

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

Text.data

文本节点的内容为字符串。

注意

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

2.11 ProcessingInstruction对象

表示XML文档中的处理指令; 这从Node接口继承并且不能有子节点。

ProcessingInstruction.target

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

ProcessingInstruction.data

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

2.12 Exceptions

2.1版本中的新功能。

DOM Level 2建议定义了一个单例，DOMException和一些允许应用程序确定发生的错误的常量。 DOMException实例携带一个代码属性，为特定的异常提供适当的值。

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.WrongDocumentErr

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

DOM建议中定义的异常代码根据此表映射到上述异常：

3.一致性

本节介绍Python DOM API，W3C DOM推荐和Python的OMG IDL映射之间的一致性要求和关系。

3.1 类型映射

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

此外，DOMString建议中定义的内容将映射到Python字符串或Unicode字符串。每当从DOM返回字符串时，应用程序应该能够处理Unicode。

IDL null值被映射到None，只要nullAPI允许，该值可以被实现接受或提供。

3.2 访问器方法

从OMG IDL到Python attribute的映射以Java映射的方式为IDL 声明定义访问器函数。映射IDL声明

readonly attribute string someValue;
         attribute string anotherValue;

产生三种存取器函数：一个“获取”方法someValue（_get_someValue()），和“获取”和“设置”为方法anotherValue（_get_anotherValue()和_set_anotherValue()）。映射，尤其是不需要的IDL属性是访问正常的Python属性：object.someValue是不是工作需要，并且可能引发AttributeError。

但是，Python DOM API 确实需要正常的属性访问。这意味着由Python IDL编译器生成的典型代理不可能工作，并且如果通过CORBA访问DOM对象，则可能需要在客户端上包装对象。虽然这确实需要对CORBA DOM客户端进行一些额外的考虑，但具有从Python使用DOM到CORBA的经验的实施者并不认为这是一个问题。所声明的属性readonly可能不会限制所有DOM实现中的写入访问。

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

IDL定义并未完全体现W3C DOM API的要求，例如某些对象的概念，如返回值为getElementsByTagName()“live”。Python DOM API不需要实现来执行这些需求。