xml.dom --- The Document Object Model API¶
ソースコード: Lib/xml/dom/__init__.py
文書オブジェクトモデル (Document Object Model)、すなわち "DOM" は、ワールドワイドウェブコンソーシアム (World Wide Web Consortium, W3C) による、XML ドキュメントにアクセスしたり変更を加えたりするための、プログラミング言語間共通の API です。DOM 実装によって、XML ドキュメントはツリー構造として表現されます。また、クライアントコード側でツリー構造をゼロから構築できるようになります。さらに、前述の構造に対して、よく知られたインターフェースをもつ一連のオブジェクトを通したアクセス手段も提供します。
DOM はランダムアクセスを行うアプリケーションで非常に有用です。SAX では、一度に閲覧することができるのはドキュメントのほんの一部分です。ある SAX 要素に注目している際には、別の要素をアクセスすることはできません。またテキストノードに注目しているときには、その中に入っている要素をアクセスすることができません。SAX によるアプリケーションを書くときには、プログラムがドキュメント内のどこを処理しているのかを追跡するよう、コードのどこかに記述する必要があります。SAX 自体がその作業を行ってくれることはありません。さらに、XML ドキュメントに対する先読み (look ahead) が必要だとすると不運なことになります。
アプリケーションによっては、ツリーにアクセスできなければイベント駆動モデルを実現できません。もちろん、何らかのツリーを SAX イベントに応じて自分で構築することもできるでしょうが、DOM ではそのようなコードを書かなくてもよくなります。DOM は XML データに対する標準的なツリー表現なのです。
文書オブジェクトモデルは、W3C によっていくつかの段階、W3C の用語で言えば "レベル (level)" で定義されています。Python においては、DOM API への対応付けは実質的には DOM レベル 2 勧告に基づいています。
DOM アプリケーションは、普通は XML を DOM に解析するところから始まります。どのようにして解析を行うかについては DOM レベル 1 では全くカバーしておらず、レベル 2 では限定的な改良だけが行われました: レベル 2 では Document を生成するメソッドを提供する DOMImplementation オブジェクトクラスがありますが、実装に依存しない方法で XML リーダ(reader)/パーザ(parser)/文書ビルダ (Document builder) にアクセスする方法はありません。また、既存の Document オブジェクトなしにこれらのメソッドにアクセスするような、よく定義された方法もありません。 Python では、各々の DOM 実装で getDOMImplementation() が定義されているはずです。 DOM レベル 3 ではロード(Load)/ストア(Store) 仕様が追加され、リーダのインターフェースにを定義していますが、Python 標準ライブラリではまだ利用することができません。
DOM 文書オブジェクトを生成したら、そのプロパティとメソッドを使って XML 文書の一部にアクセスできます。これらのプロパティは DOM 仕様で定義されています; 本リファレンスマニュアルでは、Python において DOM 仕様がどのように解釈されているかを記述しています。
W3C から提供されている仕様は、 DOM API を Java、ECMAScript、および OMG IDL で定義しています。ここで定義されている Python での対応づけは、大部分がこの仕様の IDL 版に基づいていますが、厳密な準拠は必要とされていません (実装で IDL の厳密な対応付けをサポートするのは自由ですが)。API への対応付けに関する詳細な議論は 適合性 を参照してください。
参考
- Document Object Model (DOM) Level 2 Specification
Python DOM API が準拠している W3C 勧告。
- Document Object Model (DOM) Level 1 Specification
xml.dom.minidomでサポートされている W3C の DOM に関する勧告。- Python Language Mapping Specification
このドキュメントでは OMG IDL から Python への対応付けを記述しています。
モジュールコンテンツ¶
xml.dom には以下の関数があります:
- xml.dom.registerDOMImplementation(name, factory)¶
ファクトリ関数 (factory function) factory を名前 name で登録します。ファクトリ関数は
DOMImplementationインターフェースを実装するオブジェクトを返さなければなりません。特定の実装 (例えば実装が何らかのカスタマイズをサポートしている場合) に適切となるように、ファクトリ関数は毎回同じオブジェクトを返したり、呼び出しごとに新しいオブジェクトを返したりすることが出来ます。
- xml.dom.getDOMImplementation(name=None, features=())¶
適切な DOM 実装を返します。name は、よく知られた DOM 実装のモジュール名か、
Noneになります。Noneでない場合、対応するモジュールを import して、import が成功した場合DOMImplementationオブジェクトを返します。 name が与えられておらず、環境変数PYTHON_DOMが設定されていた場合、 DOM 実装を見つけるのに環境変数が使われます。name が与えられない場合、利用可能な実装を調べて、指定された機能 (feature) セットを持つものを探します。実装が見つからなければ
ImportErrorを送出します。 features のリストは(feature, version)のペアからなるシーケンスで、利用可能なDOMImplementationオブジェクトのhasFeature()メソッドに渡されます。
いくつかの便利な定数も提供されています:
- xml.dom.EMPTY_NAMESPACE¶
DOM 内のノードに名前空間が何も関連づけられていないことを示すために使われる値です。この値は通常、ノードの
namespaceURIの値として見つかったり、名前空間特有のメソッドに対する namespaceURI パラメタとして使われます。
- xml.dom.XML_NAMESPACE¶
Namespaces in XML (4 節) で定義されている、予約済みプレフィクス (reserved prefix)
xmlに関連付けられた名前空間 URI です。
- xml.dom.XMLNS_NAMESPACE¶
Document Object Model (DOM) Level 2 Core Specification (1.1.8 節) で定義されている、名前空間宣言への名前空間 URI です。
- xml.dom.XHTML_NAMESPACE¶
XHTML 1.0: The Extensible HyperText Markup Language (3.1.1 節) で定義されている、XHTML 名前空間 URI です。
加えて、 xml.dom には基底となる Node クラスと DOM 例外クラスが収められています。このモジュールで提供されている Node クラスは DOM 仕様で定義されているメソッドや属性は何ら実装していません; これらは具体的な DOM 実装において提供しなければなりません。このモジュールの一部として提供されている Node クラスでは、具体的な Node オブジェクトの nodeType 属性として使う定数を提供しています; これらの定数は、DOM 仕様に適合するため、クラスではなくモジュールのレベルに配置されています。
DOM 内のオブジェクト¶
DOM について最も明確に限定しているドキュメントは W3C による DOM 仕様です。
DOM 属性は単純な文字列としてだけではなく、ノードとして操作されるかもしれないので注意してください。とはいえ、そうしなければならない場合はかなり稀なので、今のところ記述されていません。
インターフェース |
節 |
目的 |
|---|---|---|
|
根底にある実装へのインターフェース。 |
|
|
ドキュメント内の大部分のオブジェクトに対する基底インターフェース。 |
|
|
ノード列に対するインターフェース。 |
|
|
ドキュメントの処理に必要な宣言についての情報。 |
|
|
ドキュメント全体を表現するオブジェクト。 |
|
|
ドキュメント階層内の要素ノード。 |
|
|
要素ノード上の属性値ノード。 |
|
|
ソースドキュメント内のコメント表現。 |
|
|
ドキュメント内のテキスト記述を含むノード。 |
|
|
処理命令 (processing instruction) 表現。 |
さらに追加の節として、Python で DOM を利用するために定義されている例外について記述しています。
DOMImplementation オブジェクト¶
DOMImplementation インターフェースは、利用している DOM 実装において特定の機能が利用可能かどうかを決定するための方法をアプリケーションに提供します。DOM レベル 2 では、 DOMImplementation を使って新たな Document オブジェクトや DocumentType オブジェクトを生成する機能も追加しています。
- DOMImplementation.hasFeature(feature, version)¶
機能名 feature とバージョン番号 version で識別される機能（feature）が実装されていれば
Trueを返します。
- DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)¶
新たな(DOMのスーパークラスである)
Documentクラスのオブジェクトを返します。このクラスは namespaceUri と qualifiedName が設定された子クラスElementのオブジェクトを所有しています。 doctype はcreateDocumentType()によって生成されたDocumentTypeクラスのオブジェクト、またはNoneである必要があります。 Python DOM APIでは、子クラスであるElementを作成しないことを示すために、はじめの２つの引数をNoneに設定することができます。
- DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)¶
新たな
DocumentTypeクラスのオブジェクトを返します。このオブジェクトは qualifiedName 、 publicId 、そして systemId 文字列をふくんでおり、XML文書の形式情報を表現しています。
Node オブジェクト¶
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オブジェクトで定義されています。読み出し専用の属性です。
- Node.parentNode¶
現在のノードの親ノードか、文書ノードの場合には
Noneになります。この値は常にNodeオブジェクトかNoneになります。Elementノードの場合、この値はルート要素 (root element) の場合を除き親要素 (parent element) となり、ルート要素の場合にはDocumentオブジェクトとなります。Attrノードの場合、この値は常にNoneとなります。読み出し専用の属性です。
- Node.attributes¶
属性オブジェクトの
NamedNodeMapです。要素だけがこの属性に実際の値を持ちます; その他のオブジェクトでは、この属性をNoneにします。読み出し専用の属性です。
- Node.previousSibling¶
このノードと同じ親ノードを持ち、直前にくるノードです。例えば、self 要素の開始タグの直前にくる終了タグを持つ要素です。もちろん、XML 文書は要素だけで構成されているだけではないので、直前にくる兄弟関係にある要素 (sibling) はテキストやコメント、その他になる可能性があります。このノードが親ノードにおける先頭の子ノードである場合、属性値は
Noneになります。読み出し専用の属性です。
- Node.nextSibling¶
このノードと同じ親ノードを持ち、直後にくるノードです。例えば、
previousSiblingも参照してください。このノードが親ノードにおける末尾の子ノードである場合、属性値は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を返します。このメソッドは、何らかのプロキシ (proxy) 機構を利用するような DOM 実装で特に便利です (一つ以上のオブジェクトが同じノードを参照するかもしれないからです)。注釈
このメソッドは DOM レベル 3 API の提案に基づいたもので、まだ "ワーキングドラフト(working draft)" の段階です。しかし、このインターフェースには異論は出ないと考えられます。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)¶
このノードを複製 (clone) します。deep を設定すると、子ノードも同様に複製することを意味します。複製されたノードを返します。
NodeList オブジェクト¶
NodeList はノードのシーケンスを表現します。
これらのオブジェクトは DOM コア勧告 (DOM Core recommendation) において、二通りに使われています: Element オブジェクトでは、子ノードのリストを提供するのに NodeList を利用します。
また、このインターフェースにおける Node の getElementsByTagName() および getElementsByTagNameNS() メソッドは、クエリに対する結果を表現するのに NodeList を利用します。
DOM レベル 2 勧告では、これらのオブジェクトに対し、以下のようにメソッドを一つ、属性を一つ定義しています。
- NodeList.item(i)¶
存在する場合シークエンスの i 番目の要素を、そうでない場合
Noneを返します。i は 0 未満やシークエンスの長さ以上であってはなりません。
- NodeList.length¶
シーケンス中のノードの数です。
この他に、Python の DOM インターフェースでは、 NodeList オブジェクトを Python のシーケンスとして使えるようにするサポートが追加されていることが必要です。 NodeList の実装では、全て __len__() と __getitem__() をサポートしなければなりません; このサポートにより、 for 文内で NodeList にわたる繰り返しと、組み込み関数 len() の適切なサポートができるようになります。
DOM 実装が文書の変更をサポートしている場合、 NodeList の実装でも __setitem__() および __delitem__() メソッドをサポートしなければなりません。
DocumentType オブジェクト¶
文書で宣言されている記法 (notation) やエンティティ (entity) に関する (外部サブセット(external subset) がパーザから利用でき、情報を提供できる場合にはそれも含めた) 情報は、 DocumentType オブジェクトから手に入れることができます。文書の DocumentType は、 Document オブジェクトの doctype 属性で入手することができます; 文書の DOCTYPE 宣言がない場合、文書の doctype 属性は、このインターフェースを持つインスタンスの代わりに None に設定されます。
DocumentType は Node を特殊化したもので、以下の属性を加えています:
- DocumentType.publicId¶
文書型定義 (document type definition) の外部サブセットに対する公開識別子 (public identifier) です。文字列または
Noneになります。
- DocumentType.systemId¶
文書型定義 (document type definition) の外部サブセットに対するシステム識別子 (system identifier) です。文字列の URI または
Noneになります。
- DocumentType.internalSubset¶
ドキュメントの完全な内部サブセットを与える文字列です。サブセットを囲むブラケットは含みません。ドキュメントが内部サブセットを持たない場合、この値は
Noneです。
- DocumentType.name¶
DOCTYPE宣言でルート要素の名前が与えられている場合、その値になります。
- DocumentType.entities¶
外部エンティティの定義を与える
NamedNodeMapです。複数回定義されているエンティティに対しては、最初の定義だけが提供されます (その他は XML 勧告での要求仕様によって無視されます)。パーザによって情報が提供されないか、エンティティが定義されていない場合には、この値はNoneになることがあります。
- DocumentType.notations¶
記法の定義を与える
NamedNodeMapです。複数回定義されている記法名に対しては、最初の定義だけが提供されます (その他は XML 勧告での要求仕様によって無視されます)。パーザによって情報が提供されないか、エンティティが定義されていない場合には、この値はNoneになることがあります。
Document オブジェクト¶
Document は XML ドキュメント全体を表現し、その構成要素である要素、属性、処理命令、コメント等を持ちます。 Document は Node からプロパティを継承していることを思い出してください。
- Document.documentElement¶
ドキュメントの唯一無二のルート要素です。
- Document.createElement(tagName)¶
新たな要素ノードを生成して返します。要素は、生成された時点ではドキュメント内に挿入されません。
insertBefore()やappendChild()のような他のメソッドの一つを使って明示的に挿入を行う必要があります。
- Document.createElementNS(namespaceURI, tagName)¶
名前空間を伴う新たな要素ノードを生成して返します。 tagName には接頭辞 (prefix) があってもかまいません。要素は、生成された時点では文書内に挿入されません。
insertBefore()やappendChild()のような他のメソッドの一つを使って明示的に挿入を行う必要があります。
- Document.createTextNode(data)¶
引数として渡されたデータの入ったテキストノードを生成して返します。他の生成 (create) メソッドと同じく、このメソッドは生成されたノードをツリーに挿入しません。
- Document.createComment(data)¶
引数として渡されたデータの入ったコメントノードを生成して返します。他の生成 (create) メソッドと同じく、このメソッドは生成されたノードをツリーに挿入しません。
- Document.createProcessingInstruction(target, data)¶
引数として渡された target および data の入った処理命令ノードを生成して返します。他の生成 (create) メソッドと同じく、このメソッドは生成されたノードをツリーに挿入しません。
- Document.createAttribute(name)¶
属性ノードを生成して返します。このメソッドは属性ノードを特定の要素に関連づけることはしません。新たに生成された属性インスタンスを使うには、適切な
ElementオブジェクトのsetAttributeNode()を使わなければなりません。
- Document.createAttributeNS(namespaceURI, qualifiedName)¶
名前空間を伴う新たな属性ノードを生成して返します。 tagName には接頭辞 (prefix) があってもかまいません。このメソッドは属性ノードを特定の要素に関連づけることはしません。新たに生成された属性インスタンスを使うには、適切な
ElementオブジェクトのsetAttributeNode()を使わなければなりません。
- Document.getElementsByTagName(tagName)¶
全ての下位要素 (直接の子要素、子要素の子要素等) から特定の要素型名を持つものを検索します。
- Document.getElementsByTagNameNS(namespaceURI, localName)¶
全ての下位要素 (直接の子要素、子要素の子要素等) から特定の名前空間 URI とローカル名 (local name) を持つものを検索します。ローカル名は名前空間における接頭辞以降の部分です。
Element オブジェクト¶
Element は Node のサブクラスです。このため 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)¶
名前で指定された属性を削除します。このメソッドは qname ではなく localName を使うので注意してください。該当する属性がなくても例外は送出されません。
- 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 を継承しており、全ての属性を継承しています。
- Attr.name¶
要素型名です。名前空間使用の文書では、要素型名中にコロンが含まれるかもしれません。
- Attr.localName¶
名前にコロンがあればコロン以降の部分に、なければ名前全体になります。
- Attr.prefix¶
名前にコロンがあればコロン以前の部分に、なければ空文字列になります。
- Attr.value¶
その要素の text value. これは
nodeValue属性の別名です。
NamedNodeMap Objects¶
NamedNodeMap は Node を継承して いません 。
- NamedNodeMap.length¶
属性リストの長さです。
- NamedNodeMap.item(index)¶
特定のインデクスを持つ属性を返します。属性の並び方は任意ですが、 DOM 文書が生成されている間は一定になります。各要素は属性ノードです。属性値はノードの
value属性で取得してください。
このクラスをよりマップ型的な動作ができるようにする実験的なメソッドもあります。そうしたメソッドを使うこともできますし、 Element オブジェクトに対して、標準化された getAttribute*() ファミリのメソッドを使うこともできます。
Text オブジェクトおよび CDATASection オブジェクト¶
Text インターフェースは XML 文書内のテキストを表現します。パーザおよび DOM 実装が DOM の XML 拡張をサポートしている場合、 CDATA でマークされた区域 (section) に入れられている部分テキストは CDATASection オブジェクトに記憶されます。これら二つのインターフェースは同一のものですが、 nodeType 属性が異なります。
これらのインターフェースは Node インターフェースを拡張したものです。しかし子ノードを持つことはできません。
- Text.data¶
文字列によるテキストノードの内容です。
注釈
CDATASection ノードの利用は、ノードが完全な CDATA マーク区域を表現するという意味ではなく、ノードの内容が CDATA 区域の一部であるということを意味するだけです。単一の CDATA セクションは文書ツリー内で複数のノードとして表現されることがあります。二つの隣接する CDATASection ノードが、異なる CDATA マーク区域かどうかを決定する方法はありません。
ProcessingInstruction オブジェクト¶
XML 文書内の処理命令を表現します; Node インターフェースを継承していますが、子ノードを持つことはできません。
- ProcessingInstruction.target¶
最初の空白文字までの処理命令の内容です。読み出し専用の属性です。
- ProcessingInstruction.data¶
最初の空白文字以降の処理命令の内容です。
例外¶
DOM レベル 2 勧告では、単一の例外 DOMException と、どの種のエラーが発生したかをアプリケーションが決定できるようにする多くの定数を定義しています。 DOMException インスタンスは、特定の例外に関する適切な値を提供する code 属性を伴っています。
Python DOM インターフェースでは、上記の定数を提供していますが、同時に一連の例外を拡張して、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¶
Namespaces in 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 勧告で定義されている例外コードは、以下のテーブルに従って上記の例外と対応付けられます:
定数 |
例外 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
適合性¶
この節では適合性に関する要求と、Python DOM API、W3C DOM 勧告、および OMG IDL の Python API への対応付けとの間の関係について述べます。
型の対応付け¶
DOM 仕様で使われている IDL 型は、以下のテーブルに従って Python の型に対応付けられています。
IDL 型 |
Python の型 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
アクセサメソッド¶
OMG IDL から Python への対応付けは、IDL attribute 宣言へのアクセサ関数の定義を、Java による対応付けが行うのとほとんど同じように行います。IDL 宣言の対応付け
readonly attribute string someValue;
attribute string anotherValue;
は、三つのアクセサ関数: someValue に対する "get" メソッド (_get_someValue())、そして anotherValue に対する "get" および "set" メソッド (_get_anotherValue() および _set_anotherValue()) を生成します。とりわけ、対応付けでは、IDL 属性が通常の Python 属性としてアクセス可能であることは必須ではありません: 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 はこれらの要件を実装することを強制しません。
Comment オブジェクト¶
Commentは XML 文書中のコメントを表現します。CommentはNodeのサブクラスですが、子ノードを持つことはありません。文字列によるコメントの内容です。この属性には、コメントの先頭にある
<!--と末尾にある-->間の全ての文字が入っていますが、<!--と-->自体は含みません。