pytho****@googl*****
pytho****@googl*****
2011年 11月 21日 (月) 11:43:32 JST
2 new revisions: Revision: 0a70184b8d75 Author: Naoki INADA <inada****@klab*****> Date: Sun Nov 20 18:42:00 2011 Log: Update 2.7.2: xml.etree.elementtree http://code.google.com/p/python-doc-ja/source/detail?r=0a70184b8d75 Revision: 355ec5c93e59 Author: Naoki INADA <inada****@klab*****> Date: Sun Nov 20 18:42:19 2011 Log: merge http://code.google.com/p/python-doc-ja/source/detail?r=355ec5c93e59 ============================================================================== Revision: 0a70184b8d75 Author: Naoki INADA <inada****@klab*****> Date: Sun Nov 20 18:42:00 2011 Log: Update 2.7.2: xml.etree.elementtree http://code.google.com/p/python-doc-ja/source/detail?r=0a70184b8d75 Modified: /library/xml.etree.elementtree.rst /library/xml.etree.elementtree.rst.diff ======================================= --- /library/xml.etree.elementtree.rst Fri Mar 18 22:54:15 2011 +++ /library/xml.etree.elementtree.rst Sun Nov 20 18:42:00 2011 @@ -9,7 +9,8 @@ .. versionadded:: 2.5 -エレメント型は柔軟性のあるコンテナオブジェクトで、階層的データ構造をメモ リーに格納するようにデザインされています。この型は言わばリストと辞書の\ +:class:`Element` 型は柔軟性のあるコンテナオブジェクトで、階層的データ構造を +メモリーに格納するようにデザインされています。この型は言わばリストと辞書の 間の子のようなものです。 各エレメントは関連する多くのプロパティを具えています: @@ -24,7 +25,8 @@ * 幾つもの子エレメント(Python シーケンスに収められます) -エレメントのインスタンスを作るには、Element や SubElement といったファクト リー関数を使います。 +element のインスタンスを作るには、 :class:`Element` コンストラクタや +:func:`SubElement` ファクトリー関数を使います。 :class:`ElementTree` クラスはエレメントの構造を包み込み、それと XML を行き 来するのに使えます。 @@ -32,7 +34,13 @@ チュートリアルその他のドキュメントへのリンクについては http://effbot.org/zone/element-index.htm を参照して下さい。 -Fredrik Lundh のページも xml.etree.ElementTree の開発バージョンの置き場所 です。 +Fredrik Lundh のページも xml.etree.ElementTree の開発バージョンの置き場所で す。 + +.. versionchanged:: 2.7 + ElementTree API が 1.3 に更新されました。 + より詳しい情報については、 + `Introducing ElementTree 1.3 <http://effbot.org/zone/elementtree-13-intro.htm>`_ + を参照してください。 .. _elementtree-functions: @@ -41,10 +49,12 @@ ---- -.. function:: Comment([text]) - - コメント・エレメントのファクトリーです。このファクトリー関数は XML コメ ントにシリアライズされる特別な要素を作ります。コメント文字列は、8-bit - ASCII 文字列でも Unicode 文字列でも構いません。 *text* はそのコメント文 字列を含んだ文字列です。 +.. function:: Comment(text=None) + + コメント・エレメントのファクトリーです。このファクトリー関数は、標準のシ リアライザでは + XML コメントにシリアライズされる特別な要素を作ります。コメント文字列は byte + 文字列でも Unicode 文字列でも構いません。 + *text* はそのコメント文字列を含んだ文字列です。 コメントを表わすエレメントのインスタンスを返します。 @@ -57,21 +67,22 @@ *elem* はエレメントの木もしくは個別のエレメントです。 -.. function:: Element(tag[, attrib][, **extra]) - - エレメントのファクトリー。この関数は標準エレメント・インタフェースを実装 したオブジェクトを返します。このオブジェクトのクラスや型が正確に何であるかは - 実装に依存しますが、いつでもこのモジュールにある _ElementInterface クラ スと互換性があります。 - - エレメント名、アトリビュート名およびアトリビュート値は8-bit ASCII 文字列 でも Unicode 文字列でも構いません。 *tag* - はエレメント名です。 *attrib* はオプションの辞書で、エレメントのアトリビ ュートを含んでいます。 *extra* - は追加のアトリビュートで、キーワード引数として与えられたものです。 - エレメント・インスタンスを返します。 - - -.. function:: fromstring(text) - - 文字列定数で与えられた XML 断片を構文解析します。XML 関数と同じです。 *text* は XML データを含んだ文字列です。 - Element インスタンスを返します。 +.. function:: fromstring(text) + + 文字列定数で与えられた XML 断片を構文解析します。 :func:`XML` 関数と + 同じです。 *text* は XML データの文字列です。 + :class:`Element` インスタンスを返します。 + + +.. function:: fromstringlist(sequence, parser=None) + + 文字列のシーケンスからXMLドキュメントを解析します。 + *sequence* は XML データのフラグメントを格納した、 list かその他のシーケ ンスです。 + *parser* はオプションの parser インスタンスです。指定されなかった場合、 + 標準の :class:`XMLParser` パーサーが利用されます。 + :class:`Elment` インスタンスを返します。 + + .. versionadded:: 2.7 .. function:: iselement(element) @@ -80,10 +91,13 @@ 引数がエレメント・オブジェクトならば真値を返します。 -.. function:: iterparse(source[, events]) +.. function:: iterparse(source, events=None, parser=None) XML 断片を構文解析してエレメントの木を漸増的に作っていき、その間進行状況 をユーザーに報告します。 *source* は XML - データを含むファイル名またはファイル風オブジェクト。 *events* は報告すべ きイベントのリスト。省略された場合は "end" イベントだけが報告されます。 + データを含むファイル名またはファイル風オブジェクト。 *events* は報告すべ きイベントのリスト。 + 省略された場合は "end" イベントだけが報告されます。 + *parser* はオプションの引数で、パーサーのインスタンスを指定します。 + 指定されなかった場合は標準の :class:`XMLParser` が利用されます。 ``(event, elem)`` ペアのイテレータ(:term:`iterator`)を返します。 .. note:: @@ -96,14 +110,16 @@ 全部が揃ったエレメントが必要ならば、"end" イベントを探すようにして下 さい。 -.. function:: parse(source[, parser]) - - XML 断片を構文解析してエレメントの木にしていきます。 *source* は XML データを含むファイル名またはファイル風オブジェクト。 *parser* - はオプションの構文解析器インスタンスです。これが与えられない場合、標準 の XMLTreeBuilder 構文解析器が使われます。 - ElementTree インスタンスを返します。 +.. function:: parse(source, parser=None) + + XML 断片を構文解析して element tree にします。 + *source* は XML データを含むファイル名またはファイル風オブジェクト。 *parser* + はオプションの構文解析器インスタンスです。 + これが与えられない場合、標準の :class:`XMLParser` パーサーが使われます。 + :class:`ElementTree` インスタンスを返します。 -.. function:: ProcessingInstruction(target[, text]) +.. function:: ProcessingInstruction(target, text=None) PI エレメントのファクトリー。このファクトリー関数は XML の処理命令 (processing instruction) としてシリアライズされる特別なエレメントを作ります。 *target* は PI ター ゲットを含んだ文字列です。 *text* は与えられるならば PI @@ -111,165 +127,247 @@ PI を表わすエレメント・インスタンスを返します。 +.. function:: register_namespace(prefix, uri) + + 名前空間の prefix を登録します。レジストリはグローバルで、与えられた prefix + か名前空間URI のどちらかの既存のマッピングは全て削除されます。 + *prefix* は名前空間の prefix です。 *uri* は名前空間のURIです。 + この名前空間のタグや属性は、可能な限り与えられた prefix をつけてシリアラ イズされます。 + + .. versionadded:: 2.7 + + .. function:: SubElement(parent, tag[, attrib[, **extra]]) - 部分エレメントのファクトリー。この関数はエレメント・インスタンスを作り、 それを既存のエレメントに追加します。 - - エレメント名、アトリビュート名およびアトリビュート値は 8-bit ASCII 文字 列でも Unicode 文字列でも構いません。 *parent* + 子エレメントのファクトリー。この関数はエレメント・インスタンスを作り、そ れを既存のエレメントに追加します。 + + エレメント名、アトリビュート名およびアトリビュート値は byte 文字列でも Unicode 文字列でも構いません。 *parent* は親エレメントです。 *tag* はエレメント名です。 *attrib* はオプションの 辞書で、エレメントのアトリビュートを含んでいます。 *extra* は追加のアトリビュートで、キーワード引数として与えられたものです。 エレメント・インスタンスを返します。 -.. function:: tostring(element[, encoding]) - - XML エレメントを全ての子エレメントを含めて表現する文字列を生成します。 *element* はエレメント・インスタンス。 *encoding* +.. function:: tostring(element, encoding="us-ascii", method="xml") + + XML エレメントを全ての子エレメントを含めて表現する文字列を生成します。 + *element* は :class:`Element` のインスタンスです。 *encoding* [1]_ は出力エンコーディング(デフォルトは US-ASCII)です。 + *method* は ``"xml"``, ``"html"``, ``"text"`` のいずれか(デフォルトは ``"xml"``) です。 XML データを含んだエンコードされた文字列を返します。 -.. function:: XML(text) - - 文字列定数で与えられた XML 断片を構文解析します。この関数は Python コー ドに「XML リテラル」を埋め込むのに使えます。 *text* は XML - データを含んだ文字列です。 - エレメント・インスタンスを返します。 - - -.. function:: XMLID(text) - - 文字列定数で与えられた XML 断片を構文解析し、エレメント ID からエレメン トへのマッピングを与える辞書も同時に返します。 *text* は XML - データを含んだ文字列です。 - エレメント・インスタンスと辞書のタプルを返します。 - -.. _elementtree-element-interface: - -Element インタフェース +.. function:: tostringlist(element, encoding="us-ascii", method="xml") + + XML エレメントを全ての子エレメントを含めて表現する文字列を生成します。 + *element* は :class:`Element` のインスタンスです。 *encoding* [1]_ + は出力エンコーディング(デフォルトは US-ASCII)です。 + *method* は ``"xml"``, ``"html"``, ``"text"`` のいずれか(デフォルトは ``"xml"``) です。 + XML データを含んだエンコードされた文字列のリストを返します。 + これは、 ``"".join(tostringlist(element)) == tostring(element)`` + であること以外、なにか特定のシーケンスになることは保証していません。 + + .. versionadded:: 2.7 + + +.. function:: XML(text, parser=None) + + 文字列定数で与えられた XML 断片を構文解析します。この関数は Python コー ドに + 「XML リテラル」を埋め込むのに使えます。 *text* は XML データを含んだ文 字列です。 + *parser* はオプションで、パーサーのインスタンスです。指定されなかった場 合は、 + 標準の :class:`XMLParser` パーサーを利用します。 + :class:`Element` のインスタンスを返します。 + + +.. function:: XMLID(text, parser=None) + + 文字列定数で与えられた XML 断片を構文解析し、エレメント ID からエレメン ト + へのマッピングを与える辞書も同時に返します。 *text* は XMLデータを + 含んだ文字列です。 + *parser* はオプションで、パーサーのインスタンスです。指定されなかった場 合は、 + 標準の :class:`XMLParser` パーサーを利用します。 + :class:`Element` のインスタンスと辞書のタプルを返します。 + + +.. _elementtree-element-objects: + +Element オブジェクト ---------------------- -Element や SubElement が返す Element オブジェクトには以下のメソッドとアトリ ビュートがあります。 - -.. attribute:: Element.tag - - このエレメントが表すデータの種類を示す文字列です(言い替えるとエレメント の型です)。 - -.. attribute:: Element.text - - *text* アトリビュートはエレメントに結びつけられた付加的なデータを保持す るのに使われます。 - 名前が示唆しているようにこのアトリビュートはたいてい文字列ですがアプリ ケーション固有のオブジェクトであって構いません。 - エレメントが XML ファイルから作られたものならば、このアトリビュートはエ レメント・タグの間にあるテキストを丸ごと含みます。 - - -.. attribute:: Element.tail - - *tail* アトリビュートはエレメントに結びつけられた付加的なデータを保持す るのに使われます。 - このアトリビュートはたいてい文字列ですがアプリケーション固有のオブジェク トであって構いません。 - エレメントが XML ファイルから作られたものならば、このアトリビュートはエ レメントの終了タグと次のタグの直前までの間に見つかったテキストを丸ごと含みま す。 - - -.. attribute:: Element.attrib - - エレメントのアトリビュートを保持する辞書です。 - 次のことに注意しましょう。 - *attrib* は普通の書き換え可能な Python 辞書ではあるのですが、 - ElementTree の実装によっては別の内部表現を選択して要求されたときにだけ辞 書を作るようにするかもしれません。 - そうした実装の利益を享受するために、可能な限り下記の辞書メソッドを通じて 使いましょう。 - -以下の辞書風メソッドがエレメントのアトリビュートに対して働きます。 - -.. method:: Element.clear() - - エレメントをリセットします。全ての下部エレメントを削除し、アトリビュート をクリアし、 - テキストとテールのアトリビュートを ``None`` にセットします。 - - -.. method:: Element.get(key[, default=None]) - - エレメントの *key* という名前のアトリビュートを取得します。 - - アトリビュートの値、またはアトリビュートがない場合は *default* を返しま す。 +.. function:: Element(tag[, attrib][, **extra]) + + エレメントクラス。この関数は Element インタフェースを定義すると同時に、 + そのリファレンス実装を提供します。 + + エレメント名、アトリビュート名およびアトリビュート値は bytes 文字列でも + Unicode 文字列でも構いません。 *tag* はエレメント名です。 + *attrib* はオプションの辞書で、エレメントのアトリビュートを含んでいま す。 *extra* + は追加のアトリビュートで、キーワード引数として与えられたものです。 + エレメント・インスタンスを返します。 + + + + .. attribute:: tag + + このエレメントが表すデータの種類を示す文字列です(言い替えると、エレメ ントの型です)。 + + .. attribute:: text + + *text* アトリビュートはエレメントに結びつけられた付加的なデータを保持 するのに使われます。 + 名前が示唆しているようにこのアトリビュートはたいてい文字列ですが、 + アプリケーション固有のオブジェクトであって構いません。 + エレメントが XML ファイルから作られたものならば、このアトリビュートは + エレメント・タグの間にあるテキストを丸ごと含みます。 + + + .. attribute:: tail + + *tail* アトリビュートはエレメントに結びつけられた付加的なデータを保持 するのに使われます。 + このアトリビュートはたいてい文字列ですが、アプリケーション固有のオブ ジェクトであって構いません。 + エレメントが XML ファイルから作られたものならば、このアトリビュートは エレメントの + 終了タグと次のタグの直前までの間に見つかったテキストを丸ごと含みま す。 + + + .. attribute:: attrib + + エレメントのアトリビュートを保持する辞書です。 + 次のことに注意しましょう。 + *attrib* は普通の書き換え可能な Python の辞書ではあるのですが、 + ElementTree の実装によっては別の内部表現を選択して要求されたときにだ け辞書を作るようにするかもしれません。 + そうした実装の利益を享受するために、可能な限り下記の辞書メソッドを通 じて使いましょう。 + + 以下の辞書風メソッドがエレメントのアトリビュートに対して働きます。 + + .. method:: clear() + + エレメントをリセットします。全ての子孫エレメントを削除し、アトリビ ュートをクリアし、 + test と tail を ``None`` にセットします。 -.. method:: Element.items() - - エレメントのアトリビュートを (名前, 値) ペアのシーケンスとして返します。 - 返されるアトリビュートの順番は決まっていません。 - - -.. method:: Element.keys() - - エレメントのアトリビュート名をリストとして返します。 - 返される名前の順番は決まっていません。 - -.. method:: Element.set(key, value) - - エレメントのアトリビュート *key* に *value* をセットします。 - -以下のメソッドはエレメントの子(サブエレメント)に対して働きます。 - -.. method:: Element.append(subelement) - - エレメント *subelement* をこのエレメントの内部リストの最後に追加します。 - -.. method:: Element.find(match) - - *match* にマッチする最初のサブエレメントを探します。 - *match* はタグ名かパス(path)です。 - エレメント・インスタンスまたは ``None`` を返します。 - -.. method:: Element.findall(match) - - *match* にマッチする全てのサブエレメントを探します。 - *match* はタグ名かパス(path)です。 - マッチするエレメントの文書中での出現順に yield するイテレート可能オブジ ェクトを返します。 - -.. method:: Element.findtext(condition[, default=None]) - - *condition* にマッチする最初のサブエレメントのテキストを探します。 - *condition* はタグ名かパスです。 - 最初にマッチするエレメントのテキスト内容を返すか、エレメントが見あたらな かった場合 - *default* を返します。 - マッチしたエレメントにテキストがなければ空文字列が返されるので気を付けま しょう。 - -.. method:: Element.getchildren() - - 全てのサブエレメントを返します。エレメントは文書中での出現順に返されま す。 - -.. method:: Element.getiterator([tag=None]) - - 現在のエレメントを根とするツリーのイテレータを作ります。 - イテレータは現在のエレメントとそれ以下の全てのエレメントを、 - 文書中での出現順(深さ優先順)でイテレートします。 - *tag* が ``None`` または ``'*'`` でない場合は、 - 与えられたタグに等しいものについてのみイテレータから返されます。 - -.. method:: Element.insert(index, element) - - サブエレメントをこのエレメントの与えられた位置に挿入します。 - -.. method:: Element.makeelement(tag, attrib) - - 現在のエレメントと同じ型の新しいエレメント・オブジェクトを作ります。 - このメソッドは呼び出さずに、 SubElement ファクトリー関数を使って下さい。 - -.. method:: Element.remove(subelement) - - 現在のエレメントから *subelement* を削除します。 - findXYZ メソッド群と違ってこのメソッドはエレメントをインスタンスの同一性 で比較します。 - タグや内容では比較しません。 - -Element オブジェクトは以下のシーケンス型のメソッドをサブエレメントを操作す るためにサポートしま す: :meth:`__delitem__`, :meth:`__getitem__`, :meth:`__setitem__`, -:meth:`__len__` 。 - -要注意: Element オブジェクトでは :meth:`__nonzero__` メソッドを定義していな いので、 -サブエレメントのないエレメントは偽と判定されます。:: - - element = root.find('foo') - - if not element: # careful! - print "element not found, or element has no subelements" - - if element is None: - print "element not found" + .. method:: get(key, default=None) + + エレメントの *key* という名前のアトリビュートを取得します。 + + アトリビュートの値、またはアトリビュートがない場合は *default* を返し ます。 + + + .. method:: items() + + エレメントのアトリビュートを (名前, 値) ペアのシーケンスとして返しま す。 + 返されるアトリビュートの順番は決まっていません。 + + + .. method:: keys() + + エレメントのアトリビュート名をリストとして返します。 + 返される名前の順番は決まっていません。 + + .. method:: set(key, value) + + エレメントのアトリビュート *key* に *value* をセットします。 + + 以下のメソッドはエレメントの子(サブエレメント)に対して働きます。 + + .. method:: append(subelement) + + エレメント *subelement* をこのエレメントの内部にあるサブエレメントの + リストの最後に追加します。 + + .. method:: extend(subelements) + + シーケンスオブジェクト *subelements* から 0個以上のサブエレメントを追 加します。 + サブエレメントが有効なオブジェクトでない場合は :exc:`AssertionError` + を発生させます。 + + .. versionadded:: 2.7 + + .. method:: find(match) + + *match* にマッチする最初のサブエレメントを探します。 + *match* はタグ名かパス(path)です。 + エレメント・インスタンスまたは ``None`` を返します。 + + .. method:: findall(match) + + タグ名かパスにマッチする全てのサブエレメントを探します。 + 全てのマッチするエレメントを、ドキュメント上の順序で含むリストを返し ます。 + + .. method:: findtext(match, default=None) + + *match* にマッチする最初のサブエレメントのテキストを探します。 + *match* はタグ名かパスです。 + 最初にマッチするエレメントの text を返すか、エレメントが見あたらなか った場合 + *default* を返します。 + マッチしたエレメントに text がなければ空文字列が返されるので気を付け ましょう。 + + .. method:: getchildren() + + .. deprecated:: 2.7 + ``list(elem)`` を使うか、 Element に対してイテレートしてください。 + + .. method:: getiterator(tag=None) + + .. deprecated:: 2.7 + :meth:`Element.iter` メソッドを使ってください。 + + .. method:: insert(index, element) + + サブエレメントをこのエレメントの与えられた位置に挿入します。 + + + .. method:: iter(tag=None) + + 現在のエレメントを根とするツリーのイテレータ(:term:`iterator`)を作り ます。 + イテレータは現在のエレメントとそれ以下の全てのエレメントを、 + 文書中での出現順(深さ優先順)でイテレートします。 + *tag* が ``None`` または ``'*'`` でない場合は、 + 与えられたタグに等しいものについてのみイテレータから返されます。 + イテレート中にツリー構造が変更された場合の結果は未定義です。 + + + .. method:: iterfind(match) + + タグ名かパスにマッチする全てのサブエレメントを探します。 + 全てのマッチするエレメントをドキュメント上の順序で yield する + イテレート可能オブジェクトを返します。 + + .. versionadded:: 2.7 + + + .. method:: itertext() + + text のイテレータを作成します。 + このイテレータは、このエレメントと全てのサブエレメントをドキュメント 上の + 順序で巡回し、全ての内部の text を返します。 + + .. versionadded:: 2.7 + + + .. method:: makeelement(tag, attrib) + + 現在のエレメントと同じ型の新しいエレメント・オブジェクトを作ります。 + このメソッドは呼び出さずに、 :func:`SubElement` ファクトリー関数を使 って下さい。 + + .. method:: remove(subelement) + + 現在のエレメントから *subelement* を削除します。 + find\* メソッド群と違ってこのメソッドはエレメントをインスタンスの同一 性で比較します。 + タグや内容では比較しません。 + + :class:`Element` オブジェクトは以下のシーケンス型のメソッドを、サブエレ メントを + 操作するためにサポートしま す: :meth:`__delitem__`, :meth:`__getitem__`, :meth:`__setitem__`, + :meth:`__len__`. + + 注意: サブエレメントを持たないエレメントの真偽値は ``False`` になりま す。 + この挙動は将来のバージョンで変更されるかもしれません。 + 直接真偽値をテストするのでなく、 ``len(elem)`` か ``elem is None`` を利 用してください。 :: + + element = root.find('foo') + + if not element: # careful! + print "element not found, or element has no subelements" + + if element is None: + print "element not found" .. _elementtree-elementtree-objects: @@ -278,11 +376,13 @@ ------------------------ -.. class:: ElementTree([element,] [file]) - - ElementTree ラッパー・クラス。このクラスはエレメントの全階層を表現し、さ らに標準 XML との相互変換を追加しています。 - - *element* は根エレメントです。木はもし *file* が与えられればその XML の 内容により初期化されます。 +.. class:: ElementTree(element=None, file=None) + + ElementTree ラッパー・クラス。このクラスはエレメントの全階層を表現し、 + さらに標準 XML との相互変換を追加しています。 + + *element* は根エレメントです。 + 木はもし *file* が与えられればその XML の内容により初期化されます。 .. method:: _setroot(element) @@ -292,37 +392,35 @@ 注意して使ってください。 *element* はエレメント・インスタンスです。 - .. method:: find(path) - - 子孫エレメントの中で与えられたタグを持つ最初のものを見つけます。 - getroot().find(path) と同じです。 *path* - は探したいエレメントです。 + .. method:: find(match) + + *match* にマッチする最初のトップレベルのエレメントを探します。 + *match* はタグ名かパスです。 + getroot().find(path) と同じです。 最初に条件に合ったエレメント、または見つからない時は ``None`` を返し ます。 - .. method:: findall(path) - - 子孫エレメントの中で与えられたタグを持つものを全て見つけます。 - getroot().findall(path) と同じです。 *path* - は探したいエレメントです。 - 全ての条件に合ったエレメントのリストまたはイテレータ (:term:`iterator`)を返します、セクション順です。 + .. method:: findall(match) + + タグ名かパスにマッチする全てのサブエレメントを探します。 + getroot().findall(match) と同じです。 *match* はタグ名かパスです。 + 条件に合った全てのエレメントを、ドキュメント上の順序で格納したリスト を返します。 - .. method:: findtext(path[, default]) + .. method:: findtext(match, default=None) 子孫エレメントの中で与えられたタグを持つ最初のもののテキストを見つけ ます。 - getroot().findtext(path) と同じです。 *path* - は探したい直接の子エレメントです。 + getroot().findtext(match) と同じです。 *match* はタグ名かパスです。 *default* はエレメントが見つからなかった場合に返される値です。 条件に合った最初のエレメントのテキスト、または見つからなかった場合に はデフォルト値を返します。 - もしエレメントが見つかったもののテキストがなかった場合には、このメソ ッドは空文字列を返す、ということに気をつけてください。 + もしエレメントが見つかったもののテキストがなかった場合には、 + このメソッドは空文字列を返すということに気をつけてください。 - .. method:: getiterator([tag]) - - 根エレメントに対する木を巡るイテレータを作ります。 - イテレータは木の全てのエレメントに渡ってセクション順にループします。 - *tag* は探したいタグです(デフォルトでは全てのエレメントを返します)。 + .. method:: getiterator(tag=None) + + .. deprecated:: 2.7 + 代わりに :meth:`ElementTree.iter` メソッドを利用してください。 .. method:: getroot() @@ -330,20 +428,43 @@ この木の根エレメントを返します。 - .. method:: parse(source[, parser]) + .. method:: iter(tag=None) + + ルートエレメントに対する、ツリーを巡回するイテレータを返します。 + イテレータはツリーの全てのエレメントに渡ってセクション順にループしま す。 + *tag* は探したいタグです(デフォルトでは全てのエレメントを返します)。 + + + .. method:: iterfind(match) + + タグ名かパスにマッチする全てのサブエレメントを返します。 + getroot().iterfind(match) と同じです。 + 全てのマッチするエレメントをドキュメント順に yield するイテレート可能 + オブジェクトを返します。 + + .. versionadded:: 2.7 + + + .. method:: parse(source, parser=None) 外部の XML 断片をこのエレメントの木に読み込みます。 *source* は XML データを含むファイル名またはファイル風オブジェクト。 *parser* はオプションの構文解析器インスタンスです。 - これが与えられない場合、標準の XMLTreeBuilder 構文解析器が使われま す。 + これが与えられない場合、標準の XMLParser パーサーが使われます。 断片の根エレメントを返します。 - .. method:: write(file[, encoding]) + .. method:: write(file, encoding="us-ascii", xml_declaration=None, method="xml") エレメントの木をファイルに XML として書き込みます。 *file* はファイル名またはファイル風オブジェクトで書き込み用に開かれた もの。 *encoding* [1]_ は出力エンコーディング(デフォルトは US-ASCII)です。 + *xml_declaration* は、 XML 宣言がファイルに書かれるかどうかを制御しま す。 + False の場合は常に書かれず、 True の場合は常に書かれ、 None の場合は + US-ASCII か UTF-8 以外の場合に書かれます (デフォルトは None です)。 + *method* は ``"xml"``, ``"html"``, ``"text"`` のいづれかです + (デフォルトは ``"xml"`` です)。 + エンコードされた文字列を返します。 次に示すのがこれから操作する XML ファイルです:: @@ -363,26 +484,28 @@ >>> from xml.etree.ElementTree import ElementTree >>> tree = ElementTree() >>> tree.parse("index.xhtml") - <Element html at b7d3f1ec> + <Element 'html' at 0xb77e6fac> >>> p = tree.find("body/p") # Finds first occurrence of tag p in body >>> p - <Element p at 8416e0c> - >>> links = p.getiterator("a") # Returns list of all links + <Element 'p' at 0xb77ec26c> + >>> links = list(p.iter("a")) # Returns list of all links >>> links - [<Element a at b7d4f9ec>, <Element a at b7d4fb0c>] + [<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>] >>> for i in links: # Iterates through all found links ... i.attrib["target"] = "blank" >>> tree.write("output.xhtml") + .. _elementtree-qname-objects: QName オブジェクト ------------------ -.. class:: QName(text_or_uri[, tag]) - - QName ラッパー。このクラスは QName アトリビュート値をラップし、出力時に 真っ当な名前空間の扱いを得るために使われます。 *text_or_uri* +.. class:: QName(text_or_uri, tag=None) + + QName ラッパー。このクラスは QName アトリビュート値をラップし、出力時に + 真っ当な名前空間の扱いを得るために使われます。 *text_or_uri* は {uri}local という形式の QName 値を含む文字列、または tag 引数が与えら れた場合には QName の URI 部分の文字列です。 *tag* が与えられた場合、一つめの引数は URI と解釈され、この引数はローカ ル名と解釈されます。 :class:`QName` インスタンスは不透明です。 @@ -394,23 +517,25 @@ ------------------------ -.. class:: TreeBuilder([element_factory]) - - 汎用のエレメント構造ビルダー。これは start、data、end のメソッド呼び出し の列を整形式のエレメント構造に変換します。このクラスを使うと、好みの - XML 構文解析器、または他の XML に似た形式の構文解析器を使って、エレメン ト構造を作り出すことができます。 *element_factory* - が与えられた場合には新しいエレメント・インスタンスを作る際にこれを呼び出 します。 +.. class:: TreeBuilder(element_factory=None) + + 汎用のエレメント構造ビルダー。これは start, data, end の + メソッド呼び出しの列を整形式のエレメント構造に変換します。 + このクラスを使うと、好みの XML 構文解析器、または他の XML に似た形式の + 構文解析器を使って、エレメント構造を作り出すことができます。 *element_factory* + が与えられた場合には、新しい :class:`Element` インスタンスを作る際にこれ を呼び出します。 .. method:: close() - 構文解析器のバッファをフラッシュし、最上位の文書エレメントを返しま す。 - Element インスタンスを返します。 + ビルダーのバッファをフラッシュし、最上位の文書エレメントを返します。 + :class:`Element` インスタンスを返します。 .. method:: data(data) 現在のエレメントにテキストを追加します。 *data* は文字列です。 - 8-bit ASCII 文字列もしくは Unicode 文字列でなければなりません。 + bytes 文字列もしくは Unicode 文字列でなければなりません。 .. method:: end(tag) @@ -425,19 +550,38 @@ *attrs* はエレメントのアトリビュートを保持した辞書です。 開かれたエレメントを返します。 - -.. _elementtree-xmltreebuilder-objects: - -XMLTreeBuilder オブジェクト ---------------------------- - - -.. class:: XMLTreeBuilder([html,] [target]) + 加えて、カスタムの :class:`TreeBuilder` オブジェクトは以下のメソッドを + 提供できます。 + + .. method:: doctype(name, pubid, system) + + doctype 宣言を処理します。 *name* は doctype 名です。 + *pubid* は公式の識別子です。 *system* はシステム識別子です。 + このメソッドはデフォルトの :class:`TreeBuilder` クラスには存在しませ ん。 + + .. versionadded:: 2.7 + + +.. _elementtree-xmlparser-objects: + +XMLParser オブジェクト +----------------------- XML ソースからエレメント構造を作るもので、expat 構文解析器に基づいていま す。 *html* は前もって定義された HTML - エンティティです。このオプションは現在の実装ではサポートされていませ ん。 *target* はターゲットとなるオブジェクトです。省略された場合、標準の + エンティティです。このオプションは現在の実装ではサポートされていません。 + *target* はターゲットとなるオブジェクトです。省略された場合、標準の TreeBuilder クラスのインスタンスが使われます。 +.. class:: XMLParser(html=0, target=None, encoding=None) + + expat パーサーを利用した、XML ソースデータからの :class:`Element` 構造ビ ルダー。 + *html* は定義済みの HTML エンティティです。このフラグは現在の実装では + サポートされていません。 + *target* はターゲットオブジェクトです。省略された場合、ビルダーは + 標準の TreeBuilder クラスのインスタンスを利用します。 + *encoding* [1]_ はオプションで、与えられた場合は XML ファイルで指定され た + エンコーディングをオーバーライドします。 + .. method:: close() @@ -447,8 +591,9 @@ .. method:: doctype(name, pubid, system) - doctype 宣言を扱います。 *name* は doctype の名前です。 - *pubid* は公開識別子です。 *system* はシステム識別子です。 + .. deprecated:: 2.7 + カスタムの TreeBuilder target で :meth:`TreeBuilder.doctype` メソ ッドを + 定義してください。 .. method:: feed(data) @@ -456,14 +601,14 @@ 構文解析器にデータを供給します。 *data* はエンコードされたデータです。 -:meth:`XMLTreeBuilder.feed` は *target* の :meth:`start` メソッドを\ +:meth:`XMLParser.feed` は *target* の :meth:`start` メソッドを それぞれの開始タグに対して呼び、また :meth:`end` メソッドを終了タグに対して 呼び、 そしてデータは :meth:`data` メソッドで処理されます。 -:meth:`XMLTreeBuilder.close` は *target* の :meth:`close` メソッドを呼びま す。 -:class:`XMLTreeBuilder` は木構造を構築する以外にも使えます。 +:meth:`XMLParser.close` は *target* の :meth:`close` メソッドを呼びます。 +:class:`XMLParser` は木構造を構築する以外にも使えます。 以下の例は、XML ファイルの最高の深さを数えます:: - >>> from xml.etree.ElementTree import XMLTreeBuilder + >>> from xml.etree.ElementTree import XMLParser >>> class MaxDepth: # The target object of the parser ... maxDepth = 0 ... depth = 0 @@ -479,7 +624,7 @@ ... return self.maxDepth ... >>> target = MaxDepth() - >>> parser = XMLTreeBuilder(target=target) + >>> parser = XMLParser(target=target) >>> exampleXml = """ ... <a> ... <b> ======================================= --- /library/xml.etree.elementtree.rst.diff Sun Oct 30 17:04:23 2011 +++ /library/xml.etree.elementtree.rst.diff Sun Nov 20 18:42:00 2011 @@ -128,10 +128,10 @@ Parses an XML section into an element tree incrementally, and reports what's - going on to the user. *source* is a filename or file object containing XML data. -- *events* is a list of events to report back. If omitted, only "end" events are -- reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs. + going on to the user. *source* is a filename or file object containing XML +- *events* is a list of events to report back. If omitted, only "end" events are + data. *events* is a list of events to report back. If omitted, only "end" +- reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs. + events are reported. *parser* is an optional parser instance. If not + given, the standard :class:`XMLParser` parser is used. Returns an + :term:`iterator` providing ``(event, elem)`` pairs. @@ -151,12 +151,12 @@ +.. function:: parse(source, parser=None) - Parses an XML section into an element tree. *source* is a filename or file -- object containing XML data. *parser* is an optional parser instance. If not -- given, the standard XMLTreeBuilder parser is used. Returns an ElementTree -- instance. + Parses an XML section into an element tree. *source* is a filename or file +- object containing XML data. *parser* is an optional parser instance. If not + object containing XML data. *parser* is an optional parser instance. If +- given, the standard XMLTreeBuilder parser is used. Returns an ElementTree + not given, the standard :class:`XMLParser` parser is used. Returns an +- instance. + :class:`ElementTree` instance. @@ -164,53 +164,51 @@ +.. function:: ProcessingInstruction(target, text=None) - PI element factory. This factory function creates a special element that will -- be serialized as an XML processing instruction. *target* is a string containing -- the PI target. *text* is a string containing the PI contents, if given. Returns -- an element instance, representing a processing instruction. + PI element factory. This factory function creates a special element that +- be serialized as an XML processing instruction. *target* is a string containing + will be serialized as an XML processing instruction. *target* is a string +- the PI target. *text* is a string containing the PI contents, if given. Returns + containing the PI target. *text* is a string containing the PI contents, if +- an element instance, representing a processing instruction. + given. Returns an element instance, representing a processing instruction. --.. function:: SubElement(parent, tag[, attrib[, **extra]]) +.. function:: register_namespace(prefix, uri) - -- Subelement factory. This function creates an element instance, and appends it -- to an existing element. + + Registers a namespace prefix. The registry is global, and any existing + mapping for either the given prefix or the namespace URI will be removed. + *prefix* is a namespace prefix. *uri* is a namespace uri. Tags and + attributes in this namespace will be serialized with the given prefix, if at + all possible. -- The element name, attribute names, and attribute values can be either 8-bit -- ASCII strings or Unicode strings. *parent* is the parent element. *tag* is the -- subelement name. *attrib* is an optional dictionary, containing element -- attributes. *extra* contains additional attributes, given as keyword arguments. -- Returns an element instance. + .. versionadded:: 2.7 --.. function:: tostring(element[, encoding]) +-.. function:: SubElement(parent, tag[, attrib[, **extra]]) +.. function:: SubElement(parent, tag, attrib={}, **extra) -- Generates a string representation of an XML element, including all subelements. -- *element* is an Element instance. *encoding* is the output encoding (default is -- US-ASCII). Returns an encoded string containing the XML data. +- Subelement factory. This function creates an element instance, and appends it +- to an existing element. + Subelement factory. This function creates an element instance, and appends + it to an existing element. - ++ +- The element name, attribute names, and attribute values can be either 8-bit + The element name, attribute names, and attribute values can be either +- ASCII strings or Unicode strings. *parent* is the parent element. *tag* is the + bytestrings or Unicode strings. *parent* is the parent element. *tag* is +- subelement name. *attrib* is an optional dictionary, containing element +- attributes. *extra* contains additional attributes, given as keyword arguments. +- Returns an element instance. + the subelement name. *attrib* is an optional dictionary, containing element + attributes. *extra* contains additional attributes, given as keyword + arguments. Returns an element instance. --.. function:: XML(text) -+ +-.. function:: tostring(element[, encoding]) +.. function:: tostring(element, encoding="us-ascii", method="xml") -+ + +- Generates a string representation of an XML element, including all subelements. +- *element* is an Element instance. *encoding* is the output encoding (default is +- US-ASCII). Returns an encoded string containing the XML data. + Generates a string representation of an XML element, including all + subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is + the output encoding (default is US-ASCII). *method* is either ``"xml"``, @@ -231,6 +229,7 @@ + .. versionadded:: 2.7 + + +-.. function:: XML(text) +.. function:: XML(text, parser=None) Parses an XML section from a string constant. This function can be used to @@ -266,36 +265,31 @@ +.. class:: Element(tag, attrib={}, **extra) --.. attribute:: Element.tag + Element class. This class defines the Element interface, and provides a + reference implementation of this interface. -- A string identifying what kind of data this element represents (the element -- type, in other words). + The element name, attribute names, and attribute values can be either + bytestrings or Unicode strings. *tag* is the element name. *attrib* is + an optional dictionary, containing element attributes. *extra* contains + additional attributes, given as keyword arguments. --.. attribute:: Element.text +-.. attribute:: Element.tag + .. attribute:: tag -- The *text* attribute can be used to hold additional data associated with the -- element. As the name implies this attribute is usually a string but may be any -- application-specific object. If the element is created from an XML file the -- attribute will contain any text found between the element tags. +- A string identifying what kind of data this element represents (the element +- type, in other words). + A string identifying what kind of data this element represents (the + element type, in other words). --.. attribute:: Element.tail +-.. attribute:: Element.text + .. attribute:: text -- The *tail* attribute can be used to hold additional data associated with the -- element. This attribute is usually a string but may be any application-specific -- object. If the element is created from an XML file the attribute will contain -- any text found after the element's end tag and before the next tag. +- The *text* attribute can be used to hold additional data associated with the +- element. As the name implies this attribute is usually a string but may be any +- application-specific object. If the element is created from an XML file the +- attribute will contain any text found between the element tags. + The *text* attribute can be used to hold additional data associated with + the element. As the name implies this attribute is usually a string but + may be any application-specific object. If the element is created from @@ -303,178 +297,165 @@ + tags. --.. attribute:: Element.attrib +-.. attribute:: Element.tail + .. attribute:: tail - -- A dictionary containing the element's attributes. Note that while the *attrib* -- value is always a real mutable Python dictionary, an ElementTree implementation -- may choose to use another internal representation, and create the dictionary -- only if someone asks for it. To take advantage of such implementations, use the -- dictionary methods below whenever possible. + +- The *tail* attribute can be used to hold additional data associated with the +- element. This attribute is usually a string but may be any application-specific +- object. If the element is created from an XML file the attribute will contain +- any text found after the element's end tag and before the next tag. + The *tail* attribute can be used to hold additional data associated with + the element. This attribute is usually a string but may be any + application-specific object. If the element is created from an XML file + the attribute will contain any text found after the element's end tag and + before the next tag. --The following dictionary-like methods work on the element attributes. - + +-.. attribute:: Element.attrib + .. attribute:: attrib --.. method:: Element.clear() +- A dictionary containing the element's attributes. Note that while the *attrib* +- value is always a real mutable Python dictionary, an ElementTree implementation +- may choose to use another internal representation, and create the dictionary +- only if someone asks for it. To take advantage of such implementations, use the +- dictionary methods below whenever possible. + A dictionary containing the element's attributes. Note that while the + *attrib* value is always a real mutable Python dictionary, an ElementTree + implementation may choose to use another internal representation, and + create the dictionary only if someone asks for it. To take advantage of + such implementations, use the dictionary methods below whenever possible. -- Resets an element. This function removes all subelements, clears all -- attributes, and sets the text and tail attributes to None. +-The following dictionary-like methods work on the element attributes. + The following dictionary-like methods work on the element attributes. --.. method:: Element.get(key[, default=None]) +-.. method:: Element.clear() + .. method:: clear() -- Gets the element attribute named *key*. +- Resets an element. This function removes all subelements, clears all +- attributes, and sets the text and tail attributes to None. + Resets an element. This function removes all subelements, clears all + attributes, and sets the text and tail attributes to None. -- Returns the attribute value, or *default* if the attribute was not found. - + +-.. method:: Element.get(key[, default=None]) + .. method:: get(key, default=None) --.. method:: Element.items() +- Gets the element attribute named *key*. + Gets the element attribute named *key*. - -- Returns the element attributes as a sequence of (name, value) pairs. The -- attributes are returned in an arbitrary order. +- Returns the attribute value, or *default* if the attribute was not found. + Returns the attribute value, or *default* if the attribute was not found. --.. method:: Element.keys() + +-.. method:: Element.items() + .. method:: items() -- Returns the elements attribute names as a list. The names are returned in an -- arbitrary order. +- Returns the element attributes as a sequence of (name, value) pairs. The +- attributes are returned in an arbitrary order. + Returns the element attributes as a sequence of (name, value) pairs. The + attributes are returned in an arbitrary order. --.. method:: Element.set(key, value) +-.. method:: Element.keys() + .. method:: keys() -- Set the attribute *key* on the element to *value*. +- Returns the elements attribute names as a list. The names are returned in an +- arbitrary order. + Returns the elements attribute names as a list. The names are returned + in an arbitrary order. --The following methods work on the element's children (subelements). - + +-.. method:: Element.set(key, value) + .. method:: set(key, value) --.. method:: Element.append(subelement) +- Set the attribute *key* on the element to *value*. + Set the attribute *key* on the element to *value*. -- Adds the element *subelement* to the end of this elements internal list of -- subelements. +-The following methods work on the element's children (subelements). + The following methods work on the element's children (subelements). --.. method:: Element.find(match) +-.. method:: Element.append(subelement) + .. method:: append(subelement) -- Finds the first subelement matching *match*. *match* may be a tag name or path. -- Returns an element instance or ``None``. +- Adds the element *subelement* to the end of this elements internal list of +- subelements. + Adds the element *subelement* to the end of this elements internal list + of subelements. --.. method:: Element.findall(match) + .. method:: extend(subelements) -- Finds all subelements matching *match*. *match* may be a tag name or path. -- Returns an iterable yielding all matching elements in document order. + Appends *subelements* from a sequence object with zero or more elements. + Raises :exc:`AssertionError` if a subelement is not a valid object. + .. versionadded:: 2.7 --.. method:: Element.findtext(condition[, default=None]) - -- Finds text for the first subelement matching *condition*. *condition* may be a -- tag name or path. Returns the text content of the first matching element, or -- *default* if no element was found. Note that if the matching element has no -- text content an empty string is returned. +-.. method:: Element.find(match) + .. method:: find(match) +- Finds the first subelement matching *match*. *match* may be a tag name or path. +- Returns an element instance or ``None``. + Finds the first subelement matching *match*. *match* may be a tag name + or path. Returns an element instance or ``None``. --.. method:: Element.getchildren() - -- Returns all subelements. The elements are returned in document order. +-.. method:: Element.findall(match) + .. method:: findall(match) +- Finds all subelements matching *match*. *match* may be a tag name or path. +- Returns an iterable yielding all matching elements in document order. + Finds all matching subelements, by tag name or path. Returns a list + containing all matching elements in document order. --.. method:: Element.getiterator([tag=None]) - -- Creates a tree iterator with the current element as the root. The iterator -- iterates over this element and all elements below it, in document (depth first) -- order. If *tag* is not ``None`` or ``'*'``, only elements whose tag equals -- *tag* are returned from the iterator. + .. method:: findtext(match, default=None) +-.. method:: Element.findtext(condition[, default=None]) + +- Finds text for the first subelement matching *condition*. *condition* may be a +- tag name or path. Returns the text content of the first matching element, or +- *default* if no element was found. Note that if the matching element has no +- text content an empty string is returned. + Finds text for the first subelement matching *match*. *match* may be + a tag name or path. Returns the text content of the first matching + element, or *default* if no element was found. Note that if the matching + element has no text content an empty string is returned. --.. method:: Element.insert(index, element) - -- Inserts a subelement at the given position in this element. + .. method:: getchildren() +-.. method:: Element.getchildren() + +- Returns all subelements. The elements are returned in document order. + .. deprecated:: 2.7 + Use ``list(elem)`` or iteration. --.. method:: Element.makeelement(tag, attrib) - -- Creates a new element object of the same type as this element. Do not call this -- method, use the SubElement factory function instead. + .. method:: getiterator(tag=None) +-.. method:: Element.getiterator([tag=None]) + +- Creates a tree iterator with the current element as the root. The iterator +- iterates over this element and all elements below it, in document (depth first) +- order. If *tag* is not ``None`` or ``'*'``, only elements whose tag equals +- *tag* are returned from the iterator. + .. deprecated:: 2.7 + Use method :meth:`Element.iter` instead. --.. method:: Element.remove(subelement) - -- Removes *subelement* from the element. Unlike the findXYZ methods this method -- compares elements based on the instance identity, not on tag value or contents. + .. method:: insert(index, element) - --Element objects also support the following sequence type methods for working --with subelements: :meth:`__delitem__`, :meth:`__getitem__`, :meth:`__setitem__`, --:meth:`__len__`. +-.. method:: Element.insert(index, element) + +- Inserts a subelement at the given position in this element. + + Inserts a subelement at the given position in this element. --Caution: Because Element objects do not define a :meth:`__nonzero__` method, --elements with no subelements will test as ``False``. :: - -- element = root.find('foo') + + .. method:: iter(tag=None) -- if not element: # careful! -- print "element not found, or element has no subelements" + Creates a tree :term:`iterator` with the current element as the root. + The iterator iterates over this element and all elements below it, in + document (depth first) order. If *tag* is not ``None`` or ``'*'``, only + elements whose tag equals *tag* are returned from the iterator. If the + tree structure is modified during iteration, the result is undefined. -- if element is None: -- print "element not found" + + .. method:: iterfind(match) + @@ -493,30 +474,47 @@ + + + .. method:: makeelement(tag, attrib) +-.. method:: Element.makeelement(tag, attrib) + +- Creates a new element object of the same type as this element. Do not call this +- method, use the SubElement factory function instead. + + Creates a new element object of the same type as this element. Do not + call this method, use the :func:`SubElement` factory function instead. + + +-.. method:: Element.remove(subelement) + .. method:: remove(subelement) + +- Removes *subelement* from the element. Unlike the findXYZ methods this method +- compares elements based on the instance identity, not on tag value or contents. + Removes *subelement* from the element. Unlike the find\* methods this + method compares elements based on the instance identity, not on tag value + or contents. + +-Element objects also support the following sequence type methods for working +-with subelements: :meth:`__delitem__`, :meth:`__getitem__`, :meth:`__setitem__`, +-:meth:`__len__`. + :class:`Element` objects also support the following sequence type methods + for working with subelements: :meth:`__delitem__`, :meth:`__getitem__`, + :meth:`__setitem__`, :meth:`__len__`. + +-Caution: Because Element objects do not define a :meth:`__nonzero__` method, +-elements with no subelements will test as ``False``. :: + Caution: Elements with no subelements will test as ``False``. This behavior + will change in future versions. Use specific ``len(elem)`` or ``elem is + None`` test instead. :: + +- element = root.find('foo') + element = root.find('foo') + +- if not element: # careful! +- print "element not found, or element has no subelements" + if not element: # careful! + print "element not found, or element has no subelements" + +- if element is None: +- print "element not found" + if element is None: + print "element not found" @@ -578,14 +576,14 @@ Finds the element text for the first toplevel element with given tag. - Same as getroot().findtext(path). *path* is the toplevel element to look -- for. *default* is the value to return if the element was not -- found. Returns the text content of the first matching element, or the -- default value no element was found. Note that if the element has is -- found, but has no text content, this method returns an empty string. + Same as getroot().findtext(match). *match* may be a tag name or path. +- for. *default* is the value to return if the element was not + *default* is the value to return if the element was not found. Returns +- found. Returns the text content of the first matching element, or the + the text content of the first matching element, or the default value no +- default value no element was found. Note that if the element has is + element was found. Note that if the element is found, but has no text +- found, but has no text content, this method returns an empty string. + content, this method returns an empty string. @@ -604,12 +602,8 @@ Returns the root element for this tree. -- .. method:: parse(source[, parser]) + .. method:: iter(tag=None) -- Loads an external XML section into this element tree. *source* is a file -- name or file object. *parser* is an optional parser instance. If not -- given, the standard XMLTreeBuilder parser is used. Returns the section + Creates and returns a tree iterator for the root element. The iterator + loops over all elements in this tree, in section order. *tag* is the tag + to look for (default is to return all elements) @@ -624,10 +618,14 @@ + .. versionadded:: 2.7 + + +- .. method:: parse(source[, parser]) + .. method:: parse(source, parser=None) + +- Loads an external XML section into this element tree. *source* is a file + Loads an external XML section into this element tree. *source* is a file +- name or file object. *parser* is an optional parser instance. If not + name or file object. *parser* is an optional parser instance. If not +- given, the standard XMLTreeBuilder parser is used. Returns the section + given, the standard XMLParser parser is used. Returns the section root element. @@ -754,20 +752,21 @@ + containing element attributes. Returns the opened element. --.. _elementtree-xmltreebuilder-objects: + In addition, a custom :class:`TreeBuilder` object can provide the + following method: - --XMLTreeBuilder Objects ------------------------ + + .. method:: doctype(name, pubid, system) + Handles a doctype declaration. *name* is the doctype name. *pubid* is + the public identifier. *system* is the system identifier. This method + does not exist on the default :class:`TreeBuilder` class. --.. class:: XMLTreeBuilder([html,] [target]) + .. versionadded:: 2.7 +-.. _elementtree-xmltreebuilder-objects: + +-XMLTreeBuilder Objects +----------------------- +-.. class:: XMLTreeBuilder([html,] [target]) - Element structure builder for XML source data, based on the expat parser. *html* - are predefined HTML entities. This flag is not supported by the current @@ -859,8 +858,8 @@ .. [#] The encoding string included in XML output should conform to the - appropriate standards. For example, "UTF-8" is valid, but "UTF8" is -- not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl + appropriate standards. For example, "UTF-8" is valid, but "UTF8" is +- not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl + not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and http://www.iana.org/assignments/character-sets. - ============================================================================== Revision: 355ec5c93e59 Author: Naoki INADA <inada****@klab*****> Date: Sun Nov 20 18:42:19 2011 Log: merge http://code.google.com/p/python-doc-ja/source/detail?r=355ec5c93e59
