xml.dom– 文档对象模型API

源代码： Lib / xml / dom / __ init__.py

文档对象模型或“DOM”是来自World WideWeb Consortium（W3C）的跨语言API，用于访问和修改XML文档。DOMimplementation将XML文档呈现为树结构，或允许客户端代码从头开始构建这样的结构。然后通过一组提供着名界面的对象访问结构.

DOM对于随机访问应用程序非常有用。SAX仅允许您一次查看文档的一位。如果您正在查看一个SAXelement，则无法访问另一个SAXelement。如果您正在查看文本节点，则无法访问包含元素。当您编写SAX应用程序时，您需要在自己的代码中的某个位置跟踪程序在文档中的位置。SAX不会为你做这件事。另外，如果你需要在XML文档中展望未来，那你就是运气不好.

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

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

DOM应用程序通常首先将一些XML解析为DOM。DOM级别1完全没有涵盖这一点，而级别2只提供了有限的改进：有一个DOMImplementation提供对Document创建方法，但无法以独立于实现的方式访问XML读取器/解析器/文档构建器。如果没有现有的Document宾语。在Python中，每个DOM实现都会提供一个函数getDOMImplementation()。DOM Level 3增加了一个Load / Storespecification，它定义了一个读者的接口，但这在Python标准库中尚不可用.

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

W3C提供的规范定义了Java，ECMAScript和OMG IDL的DOM API。这里定义的Python映射很大程度上基于规范的IDLversion，但不要求严格的合规性（尽管实现可以自由地支持IDL的严格映射）。见第节一致性详细讨论制图要求.

也可以看看

文档对象模型（DOM）2级规范
Python DOM API所基于的W3C建议.
文档对象模型（DOM）1级规范
由xml.dom.minidom.
Python语言映射规范
这指定了从OMG IDL到Python的映射.

模块内容

xml.dom包含以下功能：

xml.dom.registerDOMImplementation（name, factory）

注册factory函数名称为name。工厂函数应该返回一个实现DOMImplementation接口。工厂函数可以每次返回相同的对象，或者每个调用都有一个newone，以适合特定的实现（例如，如果实现支持某些自定义）.

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

返回一个合适的DOM实现。name要么是众所周知的，要么是DOM实现的模块名称，要么是None。如果不是None，如果导入成功，则导入相应的模块并返回DOMImplementation对象。如果没有给出名字，如果环境变量PYTHON_DOM设置后，此变量用于查找实现.

如果未给出name，则会检查可用的实现以找到具有所需功能集的实现。如果找不到实现，请举起ImportError。功能列表必须是(feature,version)对的序列，它们被传递给hasFeature()方法可用的DOMImplementation objects.

还提供了一些便利常量：

xml.dom.EMPTY_NAMESPACE

用于表示没有命名空间与DMA中的节点关联的值。这通常被发现为节点的namespaceURI，或者用作namespaceURI参数到特定于命名空间的方法.

xml.dom.XML_NAMESPACE

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

xml.dom.XMLNS_NAMESPACE

名称空间声明的名称空间URI，由Document ObjectModel（DOM）Level 2 Core Specification（第1.1.8节）定义.

xml.dom.XHTML_NAMESPACE

由XHTML 1.0定义的XHTML命名空间的URI：ExtensibleHyperText标记语言（第3.1.1节）.

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

DOM中的对象

DOM的权威文档是W3C的DOM规范.

请注意，DOM属性也可以作为节点而不是简单字符串来操作。但是，你必须这样做很少见，所以这个用法没有记录.

接口 部分 目的
DOMImplementation DOMImplementation对象 与底层实现的接口.
Node 节点对象 文档中大多数对象的基本界面.
NodeList NodeList Objects 一系列节点的接口.
DocumentType DocumentType Objects 有关处理文档所需的声明的信息.
Document 文档对象 表示文件的对象.
Element 元素对象 文档层次中的元素节点.
Attr Attr对象 属性值节点onelement nodes.
Comment 评论对象 源文档中的注释表示.
Text 文本和CDATASection对象 包含文档中textualcontent的节点
ProcessingInstruction ProcessingInstruction Objects 处理指令表示

附加部分描述了使用DOMin Python定义的异常.

DOMImplementation Objects

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

DOMImplementation.hasFeature (feature, version)

如果由这对琴弦feature和version已实施.

DOMImplementation.createDocument (namespaceUri, qualifiedName, doctype）

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

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId）

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

节点对象

XML文档的所有组件都是Node.

Node.nodeType

的子类。表示节点类型的整数。类型的符号常量在Node object：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

A NamedNodeMap属性对象。只有元素具有实际值;其他人提供None对于这个属性。这是一个read-onlyattribute.

Node.previousSibling

紧跟在此节点之前的节点具有相同的父节点。例如，在self元素的开始标记。当然，XML文档不仅仅是justelements，所以以前的兄弟可以是文本，注释或其他东西。如果这个节点是父节点的第一个子节点，这个属性将是None。这是一个只读属性.

Node.nextSibling

紧跟在同一个父节点之后的节点。也可以看看previousSibling。如果这是父项的最后一个子项，则该属性为None。这是一个只读属性.

Node.childNodes

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

Node.firstChild

节点的第一个子节点，如果有的话，或None。这是一个read-onlyattribute .

Node.lastChild

节点的最后一个子节点，如果有的话，或None。这是一个read-onlyattribute .

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指的是与此节点相同的节点。这对于使用任何类型的代理体系结构的DOM实现尤其有用（因为多个对象可以引用同一个节点）.

注意

这是基于提议的DOM Level 3 API，它仍处于“workingdraft”阶段，但这个特殊的界面似乎没有争议。来自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树处理文本的应用程序.

Node.cloneNode（deep）

克隆此节点。设置deep也意味着克隆所有子节点。这回复了克隆.

NodeList Objects

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

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

NodeList.item（i）

退回i序列中的项目，如果有，或None。指令i不允许小于零或大于或等于序列的长度.

NodeList.length

序列中的节点数量

此外，Python DOM接口要求提供一些额外的支持以允许NodeList对象用作Python序列。所有NodeList实现必须包括对__len__()和__getitem__()的支持;这允许迭代NodeList for语句并适当支持len() built-infunction.

如果DOM实现支持修改文档，NodeList实现也必须支持__setitem__()和__delitem__() methods.

DocumentType Objects

有关文档声明的符号和实体的信息（包括解析器使用它并可提供信息的外部子集）可从DocumentType对象获得。DocumentType for adocument可以从Document对象的doctype属性获得;如果文件没有DOCTYPE声明，则文件的doctype属性将被设置为None而不是此接口的实例.

DocumentType是一个专业化的Node，并添加以下属性：

DocumentType.publicId

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

DocumentType.systemId

外部子集的系统标识符文档类型定义。这将是一个字符串的URI，或None.

DocumentType.internalSubset

一个字符串，给出文档中的完整内部子集。这不包括括起子集的括号。如果文件没有internalsubset，那应该是None.

DocumentType.name

DOCTYPE声明中给出的根元素的名称，ifpresent。

DocumentType.entities

这是NamedNodeMap给出外部实体的定义。对于多次定义的实体名称，仅提供第一个定义（根据XML建议的要求忽略其他定义）。这可能是None如果解析器没有提供信息，或者没有定义任何实体.

DocumentType.notations

这是一个 NamedNodeMap给出符号的定义。注释名称定义不止一次，仅提供第一个定义（根据XML建议的要求忽略其他定义）。这可能是None如果解析器没有提供信息，或者没有定义符号

文档对象

A 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）

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

Document.createAttribute (name )

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

Document.createAttributeNS(namespaceURI, qualifiedName)

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

Document.getElementsByTagName（tagName）

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

Document.getElementsByTagNameNS (namespaceURI, localName)

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

元素对象

Element是Node的子类，所以继承该类的所有属性.

Element.tagName

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

Element.getElementsByTagName (tagName )

和Document类。

Element.getElementsByTagNameNS（namespaceURI, localName）

和Document类。

Element.hasAttribute（name）

如果元素具有由name.

Element.hasAttributeNS（namespaceURI, localName）

如果元素具有由namespaceURI和localName.

Element.getAttribute（name）

返回由name作为一个字符串。如果不存在suchattribute，则返回一个空字符串，就好像该属性没有值一样.

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属性匹配则替换现有属性。如果发生替换，将返回theold属性节点。如果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 not继承自Node.

NamedNodeMap.length

属性列表的长度.

NamedNodeMap.item (index )

返回具有特定索引的属性。获得属性的顺序是任意的，但在DOM的生命周期中是一致的。每个项目都是anattribute节点。用valueattribute.

还有实验方法给这个类更多的映射行为。你可以使用它们或者你可以使用标准化的getAttribute*()在Element objects.

评论对象

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

Comment.data

注释的内容为字符串。该属性包含前导<!--和尾随-->之间的所有字符，但不包含它们.

文本和CDATASection对象

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

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

Text.data

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

注意

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

处理指令对象

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

ProcessingInstruction.target

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

ProcessingInstruction.data

第一个空白字符后面的处理指令的内容.

例外

DOM Level 2建议定义了一个例外，DOMException，以及一些允许应用程序确定发生了什么类型的错误的常量。DOMException实例带有code属性，为特定异常提供适当的值.

Python DOM接口提供常量，但也扩展了异常集，以便DOM定义的每个异常代码都存在特定的异常。实现必须提出适当的规范，每个都带有适当的值codeattribute.

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

引用上下文中不存在节点时的异常。例如，如果传入的节点在map中不存在，NamedNodeMap.removeNamedItem()会引发这种情况.

exception xml.dom.NotSupportedErr

当实现不支持所请求的对象类型或操作时，它会增加.

exception xml.dom.NoDataAllowedErr

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

exception xml.dom.NoModificationAllowedErr

试图修改不允许修改的对象（例如只读节点）时引发.

exception xml.dom.SyntaxErr

当指定了无效或非法字符串时引发.

exception xml.dom.WrongDocumentErr

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

DOM推荐中定义的异常代码根据此表映射到上面描述的异常：

常量 异常
DOMSTRING_SIZE_ERR DomstringSizeErr
HIERARCHY_REQUEST_ERR HierarchyRequestErr
INDEX_SIZE_ERR IndexSizeErr
INUSE_ATTRIBUTE_ERR InuseAttributeErr
INVALID_ACCESS_ERR InvalidAccessErr
INVALID_CHARACTER_ERR InvalidCharacterErr
INVALID_MODIFICATION_ERR InvalidModificationErr
INVALID_STATE_ERR InvalidStateErr
NAMESPACE_ERR NamespaceErr
NOT_FOUND_ERR NotFoundErr
NOT_SUPPORTED_ERR NotSupportedErr
NO_DATA_ALLOWED_ERR NoDataAllowedErr
NO_MODIFICATION_ALLOWED_ERR NoModificationAllowedErr
SYNTAX_ERR SyntaxErr
WRONG_DOCUMENT_ERR WrongDocumentErr

一致性

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

Type Mapping

DOM规范中使用的IDL类型根据下表映射到Python类型.

IDL类型 Python类型
boolean bool或int
int int
long int int
unsigned int int
DOMString str或bytes
null None

存取方法

从OMG IDL到Python的映射定义了IDL attribute声明的访问器函数，与Java映射的方式非常相似。映射IDL声明

readonly attribute string someValue;         attribute string anotherValue;

产生三个访问函数：someValue（_get_someValue()）的“get”方法，以及anotherValue的“get”和“set”方法（_get_anotherValue()和_set_anotherValue()）。特别是，映射不要求IDL属性可以作为normalPython属性访问：object.someValue是not需要工作，并且可能需要AttributeError.

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

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

// IDL定义没有完全体现W3C DOM API的要求，例如某些对象的概念，例如getElementsByTagName()的返回值，是“实时”。Python DOM API不需要实现来强制执行这些要求.

评论被关闭。