xml.dom --- 文檔對象模型 API?

DOMImplementation 對象?

DOMImplementation 接口提供了一種讓應(yīng)用程序確定他們所使用的 DOM 中某一特性可用性的方式。 DOM 第 2 級還添加了使用 DOMImplementation 來創(chuàng)建新的 Document 和 DocumentType 對象的能力。

DOMImplementation.hasFeature(feature, version)?

如果字符串對 feature 和 version 所標(biāo)識的特性已被實現(xiàn)則返回 True。

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)?

返回一個新的 Document 對象 (DOM 的根節(jié)點)，包含一個具有給定 namespaceUri 和 qualifiedName 的下級 Element 對象。 doctype 必須為由 createDocumentType() 創(chuàng)建的 DocumentType 對象，或者為 None。 在 Python DOM API 中，前兩個參數(shù)也可為 None 以表示不要創(chuàng)建任何下級 Element。

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)?

返回一個新的封裝了給定 qualifiedName, publicId 和 systemId 字符串的 DocumentType 對象，它表示包含在 XML 文檔類型聲明中的信息。

節(jié)點對象?

XML 文檔的所有組成部分都是 Node 的子類。

Node.nodeType?

一個代表節(jié)點類型的整數(shù)。 類型符號常量在 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?

當(dāng)前節(jié)點的上級，或者對于文檔節(jié)點則為 None。 該值總是一個 Node 對象或者 None。 對于 Element 節(jié)點，這將為上級元素，但對于根元素例外，在此情況下它將為 Document 對象。 對于 Attr 節(jié)點，它將總是為 None。 這是個只讀屬性。

Node.attributes?

屬性對象的 NamedNodeMap。 這僅對元素才有實際值；其它對象會為該屬性提供 None 值。 這是個只讀屬性。

Node.previousSibling?

在此節(jié)點之前具有相同上級的相鄰節(jié)點。 例如結(jié)束標(biāo)記緊接在在 self 元素的開始標(biāo)記之前的元素。 當(dāng)然，XML 文檔并非只是由元素組成，因此之前相鄰節(jié)點可以是文本、注釋或者其他內(nèi)容。 如果此節(jié)點是上級的第一個子節(jié)點，則該屬性將為 None。 這是一個只讀屬性。

Node.nextSibling?

在此節(jié)點之后具有相同上級的相鄰節(jié)點。 另請參見 previousSibling。 如果此節(jié)點是上級的最后一個子節(jié)點，則該屬性將為 None。 這是一個只讀屬性。

Node.childNodes?

包含在此節(jié)點中的節(jié)點列表。 這是一個只讀屬性。

Node.firstChild?

節(jié)點的第一個下級，如果有的話，否則為 None。 這是個只讀屬性。

Node.lastChild?

節(jié)點的最后一個下級，如果有的話，否則為 None。 這是個只讀屬性。

Node.localName?

tagName 在冒號之后的部分，如果有冒號的話，否則為整個 tagName。 該值為一個字符串。

Node.prefix?

tagName 在冒號之前的部分，如果有冒號的話，否則為空字符串。 該值為一個字符串或者為 None。

Node.namespaceURI?

關(guān)聯(lián)到元素名稱的命名空間。 這將是一個字符串或為 None。 這是個只讀屬性。

Node.nodeName?

這對于每種節(jié)點類型具有不同的含義；請查看 DOM 規(guī)格說明來了解詳情。 你總是可以從其他特征屬性例如元素的 tagName 特征屬性或?qū)傩缘?name 特征屬性獲取你能從這里獲取的信息。 對于所有節(jié)點類型，這個屬性的值都將是一個字符串或為 None。 這是一個只讀屬性。

Node.nodeValue?

這對于每種節(jié)點類型具有不同的含義；請查看 DOM 規(guī)格說明來了解詳情。 具體情況與 nodeName 的類似。 該值是一個字符串或為 None。

Node.hasAttributes()?

如果該節(jié)點具有任何屬性則返回 True。

Node.hasChildNodes()?

如果該節(jié)點具有任何子節(jié)點則返回 True。

Node.isSameNode(other)?

如果 other 指向的節(jié)點就是此節(jié)點則返回 True。 這對于使用了任何代理架構(gòu)的 DOM 實現(xiàn)來說特別有用（因為多個對象可能指向相同節(jié)點）。

備注

這是基于已提議的 DOM 第 3 等級 API，目前尚處于“起草”階段，但這個特定接口看來并不存在爭議。 來自 W3C 的修改將不會影響 Python DOM 接口中的這個方法（不過針對它的任何新 W3C API 也將受到支持）。

Node.appendChild(newChild)?

在子節(jié)點列表末尾添加一個新的子節(jié)點，返回 newChild。 如果節(jié)點已存在于樹結(jié)構(gòu)中，它將先被移除。

Node.insertBefore(newChild, refChild)?

在現(xiàn)有的子節(jié)點之前插入一個新的子節(jié)點。 它必須屬于 refChild 是這個節(jié)點的子節(jié)點的情況；如果不是，則會引發(fā) ValueError。newChild 會被返回。 如果 refChild 為 None，它會將 newChild 插入到子節(jié)點列表的末尾。

Node.removeChild(oldChild)?

移除一個子節(jié)點。 oldChild 必須是這個節(jié)點的子節(jié)點；如果不是，則會引發(fā) ValueError。 成功時 oldChild 會被返回。 如果 oldChild 將不再被繼續(xù)使用，則將調(diào)用它的 unlink() 方法。

Node.replaceChild(newChild, oldChild)?

將一個現(xiàn)有節(jié)點替換為新的節(jié)點。 這必須屬于 oldChild 是該節(jié)點的子節(jié)點的情況；如果不是，則會引發(fā) ValueError。

Node.normalize()?

合并相鄰的文本節(jié)點以便將所有文本段存儲為單個 Text 實例。 這可以簡化許多應(yīng)用程序處理來自 DOM 樹文本的操作。

Node.cloneNode(deep)?

克隆此節(jié)點。 設(shè)置 deep 表示也克隆所有子節(jié)點。 此方法將返回克隆的節(jié)點。

節(jié)點列表對象?

NodeList 代表一個節(jié)點列表。 在 DOM 核心建議中這些對象有兩種使用方式: 由 Element 對象提供作為其子節(jié)點列表，以及由 Node 的 getElementsByTagName() 和 getElementsByTagNameNS() 方法通過此接口返回對象來表示查詢結(jié)果。

DOM 第 2 層級建議為這些對象定義一個方法和一個屬性:

NodeList.item(i)?

從序列中返回第 i 項，如果序列不為空的話，否則返回 None。 索引號 i 不允許小于零或大于等于序列的長度。

NodeList.length?

序列中的節(jié)點數(shù)量。

此外，Python DOM 接口還要求提供一些額外支持來允許將 NodeList 對象用作 Python 序列。 所有 NodeList 實現(xiàn)都必須包括對 __len__() 和 __getitem__() 的支持；這樣 NodeList 就允許使用 for 語句進行迭代并能正確地支持 len() 內(nèi)置函數(shù)。

如果一個 DOM 實現(xiàn)支持文檔的修改，則 NodeList 實現(xiàn)還必須支持 __setitem__() 和 __delitem__() 方法。

文檔類型對象?

有關(guān)一個文檔所聲明的標(biāo)注和實體的信息（包括解析器所使用并能提供信息的外部子集）可以從 DocumentType 對象獲取。 文檔的 DocumentType 可從 Document 對象的 doctype 屬性中獲??；如果一個文檔沒有 DOCTYPE 聲明，則該文檔的 doctype 屬性將被設(shè)為 None 而非此接口的一個實例。

DocumentType 是 Node 是專門化，并增加了下列屬性:

DocumentType.publicId?

文檔類型定義的外部子集的公有標(biāo)識。 這將為一個字符串或者為 None。

DocumentType.systemId?

文檔類型定義的外部子集的系統(tǒng)標(biāo)識。 這將為一個字符串形式的 URI，或者為 None。

DocumentType.internalSubset?

一個給出來自文檔的完整內(nèi)部子集的字符串。 這不包括子集外面的圓括號。 如果文檔沒有內(nèi)部子集，則應(yīng)為 None。

DocumentType.name?

DOCTYPE 聲明中給出的根元素名稱，如果有的話。

DocumentType.entities?

這是給出外部實體定義的 NamedNodeMap。 對于多次定義的實體名稱，則只提供第一次的定義（其他的會按照 XML 建議被忽略）。 這可能為 None，如果解析器未提供此信息，或者如果未定義任何實體的話。

DocumentType.notations?

這是給出標(biāo)注定義的 NamedNodeMap。 對于多次定義的標(biāo)注，則只提供第一次的定義（其他的會按照 XML 建議被忽略）。 這可能為 None，如果解析器未提供此信息，或者如果未定義任何標(biāo)注的話。

Document 對象?

Document 代表一個完整的 XML 文檔，包括其組成元素、屬性、處理指令和注釋等。 請記住它會繼承來自 Node 的屬性。

Document.documentElement?

文檔唯一的根元素。

Document.createElement(tagName)?

創(chuàng)建并返回一個新的元素節(jié)點。 當(dāng)元素被創(chuàng)建時不會被插入到文檔中。 你需要通過某個其他方法例如 insertBefore() 或 appendChild() 來顯示地插入它。

Document.createElementNS(namespaceURI, tagName)?

創(chuàng)建并返回一個新的帶有命名空間的元素。 tagName 可以帶有前綴。 當(dāng)元素被創(chuàng)建時不會被插入到文檔中。 你需要通過某個其他方法例如 insertBefore() 或 appendChild() 來顯式地插入它。

Document.createTextNode(data)?

創(chuàng)建并返回一個包含作為形參被傳入的數(shù)據(jù)的文本節(jié)點。 與其他創(chuàng)建方法一樣，此方法不會將節(jié)點插入到樹中。

Document.createComment(data)?

創(chuàng)建并返回一個包含作為形參被傳入的數(shù)據(jù)的注釋節(jié)點。 與其他創(chuàng)建方法一樣，此方法不會將節(jié)點插入到樹中。

Document.createProcessingInstruction(target, data)?

創(chuàng)建并返回一個包含作為形參被傳入的 target 和 data 的處理指令節(jié)點。 與其他創(chuàng)建方法一樣，此方法不會將節(jié)點插入到樹中。

Document.createAttribute(name)?

創(chuàng)建并返回一個屬性節(jié)點。 此方法不會將屬性節(jié)點關(guān)聯(lián)到任何特定的元素。 你必須在正確的 Element 對象上使用 setAttributeNode() 來使用新創(chuàng)建的屬性實例。

Document.createAttributeNS(namespaceURI, qualifiedName)?

創(chuàng)建并返回一個帶有命名空間的屬性節(jié)點。 tagName 可以帶有前綴。 此方法不會將屬性節(jié)點關(guān)聯(lián)到任何特定的元素。 你必須在正確的 Element 對象上使用 setAttributeNode() 來使用新創(chuàng)建的屬性實例。

Document.getElementsByTagName(tagName)?

搜索全部具有特定元素類型名稱的后繼元素（直接下級、下級的下級等等）。

Document.getElementsByTagNameNS(namespaceURI, localName)?

搜索全部具有特定命名空間 URI 和 localname 的后繼元素（直接下級、下級的下級等等）。 localname 是命名空間在前綴之后的部分。

元素對象?

Element 是 Node 的子類，因此會繼承該類的全部屬性。

Element.tagName?

元素類型名稱。 在使用命名空間的文檔中它可能包含冒號。 該值是一個字符串。

Element.getElementsByTagName(tagName)?

與 Document 類中的對應(yīng)方法相同。

Element.getElementsByTagNameNS(namespaceURI, localName)?

與 Document 類中的對應(yīng)方法相同。

Element.hasAttribute(name)?

如果元素帶有名稱為 name 的屬性則返回 True。

Element.hasAttributeNS(namespaceURI, localName)?

如果元素帶有名稱為 namespaceURI 加 localName 的屬性則返回 True。

Element.getAttribute(name)?

將名稱為 name 的屬性的值作為字符串返回。 如果指定屬性不存在，則返回空字符串，就像該屬性沒有對應(yīng)的值一樣。

Element.getAttributeNode(attrname)?

返回名稱為 attrname 的屬性對應(yīng)的 Attr 節(jié)點。

Element.getAttributeNS(namespaceURI, localName)?

將名稱為 namespaceURI 加 localName 的屬性的值作為字符串返回。 如果指定屬性不存在，則返回空字符串，就像該屬性沒有對應(yīng)的值一樣。

Element.getAttributeNodeNS(namespaceURI, localName)?

將給定 namespaceURI 加 localName 的屬性的值作為節(jié)點返回。

Element.removeAttribute(name)?

移除指定名稱的節(jié)點。 如果沒有匹配的屬性，則會引發(fā) NotFoundErr。

Element.removeAttributeNode(oldAttr)?

從屬性列表中移除并返回 oldAttr，如果該屬性存在的話。 如果 oldAttr 不存在，則會引發(fā) NotFoundErr。

Element.removeAttributeNS(namespaceURI, localName)?

移除指定名稱的屬性。 請注意它是使用 localName 而不是 qname。 如果沒有匹配的屬性也不會引發(fā)異常。

Element.setAttribute(name, value)?

將屬性值設(shè)為指定的字符串。

Element.setAttributeNode(newAttr)?

將一個新的屬性節(jié)點添加到元素，當(dāng)匹配到 name 屬性時如有必要會替換現(xiàn)有的屬性。 如果發(fā)生了替換，將返回原有屬性節(jié)點。 如果 newAttr 已經(jīng)被使用，則會引發(fā) InuseAttributeErr。

Element.setAttributeNodeNS(newAttr)?

將一個新的屬性節(jié)點添加到元素，當(dāng)匹配到 namespaceURI 和 localName 屬性時如有必要會替換現(xiàn)有的屬性。 如果發(fā)生了替換，將返回原有屬性節(jié)點。 如果 newAttr 已經(jīng)被使用，則會引發(fā) InuseAttributeErr。

Element.setAttributeNS(namespaceURI, qname, value)?

將屬性值設(shè)為 namespaceURI 和 qname 所給出的字符串。 請注意 qname 是整個屬性名稱。 這與上面的方法不同。

Attr 對象?

Attr 繼承自 Node，因此會繼承其全部屬性。

Attr.name?

屬性名稱。 在使用命名空間的文檔中可能會包括冒號。

Attr.localName?

名稱在冒號之后的部分，如果有的話，否則為完整名稱。 這是個只讀屬性。

Attr.prefix?

名稱在冒號之前的部分，如果有冒號的話，否則為空字符串。

Attr.value?

屬性的文本值。 這與 nodeValue 屬性同義。

NamedNodeMap 對象?

NamedNodeMap 不是 繼承自 Node。

NamedNodeMap.length?

屬性列表的長度。

NamedNodeMap.item(index)?

返回特定帶有索引號的屬性。 獲取屬性的順序是強制規(guī)定的，但在 DOM 的生命期內(nèi)會保持一致。 其中每一項均為屬性節(jié)點。 可使用 value 屬性獲取其值。

還有一些試驗性方法給予這個類更多的映射行為。 你可以使用這些方法或者使用 Element 對象上標(biāo)準(zhǔn)化的 getAttribute*() 方法族。

注釋對象?

Comment 代表 XML 文檔中的注釋。 它是 Node 的子類，但不能擁有下級節(jié)點。

Comment.data?

注釋的內(nèi)容是一個字符串。 該屬性包含在開頭 <!-- 和末尾 --> 之間的所有字符，但不包括這兩個符號。

Text 和 CDATASection 對象?

Text 接口代表 XML 文檔中的文本。 如果解析器和 DOM 實現(xiàn)支持 DOM 的 XML 擴展，則包裹在 CDATA 標(biāo)記的節(jié)中的部分會被存儲到 CDATASection 對象中。 這兩個接口很相似，但是提供了不同的 nodeType 屬性值。

這些接口擴展了 Node 接口。 它們不能擁有下級節(jié)點。

Text.data?

字符串形式的文本節(jié)點內(nèi)容。

ProcessingInstruction 對象?

代表 XML 文檔中的處理指令。 它繼承自 Node 接口并且不能擁有下級節(jié)點。

ProcessingInstruction.target?

到第一個空格符為止的處理指令內(nèi)容。 這是個只讀屬性。

ProcessingInstruction.data?

在第一個空格符之后的處理指令內(nèi)容。

異常?

DOM 第 2 層級推薦定義一個異常 DOMException，以及多個變量用來允許應(yīng)用程序確定發(fā)生了何種錯誤。 DOMException 實例帶有 code 屬性用來提供特定異常所對應(yīng)的值。

Python DOM 接口提供了一些常量，但還擴展了異常集以使 DOM 所定義的每個異常代碼都存在特定的異常。 接口的具體實現(xiàn)必須引發(fā)正確的特定異常，它們各自帶有正確的 code 屬性值。

exception xml.dom.DOMException?

所有特定 DOM 異常所使用的異?；悺?該異常類不可被直接實例化。

exception xml.dom.DomstringSizeErr?

當(dāng)指定范圍的文本不能適配一個字符串時被引發(fā)。 此異常在 Python DOM 實現(xiàn)中尚不可用，但可從不是以 Python 編寫的 DOM 實現(xiàn)中接收。

exception xml.dom.HierarchyRequestErr?

當(dāng)嘗試插入一個節(jié)點但該節(jié)點類型不被允許時被引發(fā)。

exception xml.dom.IndexSizeErr?

當(dāng)一個方法的索引或大小參數(shù)為負值或超出允許的值范圍時被引發(fā)。

exception xml.dom.InuseAttributeErr?

當(dāng)嘗試插入一個 Attr 節(jié)點但該節(jié)點已存在于文檔中的某處時被引發(fā)。

exception xml.dom.InvalidAccessErr?

當(dāng)某個參數(shù)或操作在底層對象中不受支持時被引發(fā)。

exception xml.dom.InvalidCharacterErr?

當(dāng)某個字符串參數(shù)包含的字符在使用它的上下文中不被 XML 1.0 標(biāo)準(zhǔn)建議所允許時引發(fā)。 例如，嘗試創(chuàng)建一個元素類型名稱中帶有空格的 Element 節(jié)點將導(dǎo)致此錯誤被引發(fā)。

exception xml.dom.InvalidModificationErr?

當(dāng)嘗試修改某個節(jié)點的類型時被引發(fā)。

exception xml.dom.InvalidStateErr?

當(dāng)嘗試使用未定義或不再可用的的對象時被引發(fā)。

exception xml.dom.NamespaceErr?

如果試圖以 XML 中的命名空間 建議所不允許的方式修改任何對象，則會引發(fā)此異常。

exception xml.dom.NotFoundErr?

當(dāng)某個節(jié)點不存在于被引用的上下文中時引發(fā)的異常。 例如，NamedNodeMap.removeNamedItem() 將在所傳入的節(jié)點不在于于映射中時引發(fā)此異常。

exception xml.dom.NotSupportedErr?

當(dāng)具體實現(xiàn)不支持所請求的對象類型或操作時被引發(fā)。

exception xml.dom.NoDataAllowedErr?

當(dāng)為某個不支持數(shù)據(jù) 的節(jié)點指定數(shù)據(jù)時被引發(fā)。

exception xml.dom.NoModificationAllowedErr?

當(dāng)嘗試修改某個不允許修改的對象（例如只讀節(jié)點）時被引發(fā)。

exception xml.dom.SyntaxErr?

當(dāng)指定了無效或非法的字符串時被引發(fā)。

exception xml.dom.WrongDocumentErr?

當(dāng)將某個節(jié)點插入非其當(dāng)前所屬的另一個文檔，并且具體實現(xiàn)不支持從一個文檔向一個文檔遷移節(jié)點時被引發(fā)。

DOM 建議映射中針對上述異常而定義的異常代碼如下表所示:

類型映射?

將根據(jù)下表，將DOM規(guī)范中使用的IDL類型映射為Python類型。

訪問器方法?

從 OMG IDL 到 Python 的映射以類似于 Java 映射的方式定義了針對 IDL attribute 聲明的訪問器函數(shù)。 映射以下 IDL 聲明

readonly attribute string someValue;
         attribute string anotherValue;

會產(chǎn)生三個訪問器函數(shù): someValue 的 "get" 方法 (_get_someValue())，以及 anotherValue 的 "get" 和 "set" 方法 (_get_anotherValue() 和 _set_anotherValue())。 特別地，該映射不要求 IDL 屬性像普通 Python 屬性那樣可訪問: object.someValue 并非 必須可用，并可能引發(fā) AttributeError。

但是，Python DOM API 則 確實 要求普通屬性訪問可用。 這意味著由 Python IDL 解譯器生成的典型代理有可能會不可用，如果 DOM 對象是通過 CORBA 來訪問則在客戶端可能需要有包裝對象。 雖然這確實要求為 CORBA DOM 客戶端進行額外的考慮，但具有從 Python 通過 CORBA 使用 DOM 經(jīng)驗的實現(xiàn)并不會認為這是個問題。 已經(jīng)聲明了 readonly 的屬性不必在所有 DOM 實現(xiàn)中限制寫入訪問。

在 Python DOM API 中，訪問器函數(shù)不是必須的。 如果提供，則它們應(yīng)當(dāng)采用由 Python IDL 映射所定義的形式，但這些方法會被認為不必要，因為這些屬性可以從 Python 直接訪問。 永遠都不要為 readonly 屬性提供 "set" 訪問器。

IDL 定義沒有完全體現(xiàn) W3C DOM API 的要求，如特定對象的概念，又如 getElementsByTagName() 的返回值為 "live" 等。 Python DOM API 并不強制具體實現(xiàn)執(zhí)行這些要求。