19.7. xml.etree.ElementTree — ElementTree XML API

バージョン 2.5 で追加.

Source code: Lib/xml/etree/ElementTree.py

Element 型は柔軟性のあるコンテナオブジェクトで、階層的データ構造をメモリーに格納するようにデザインされています。この型は言わばリストと辞書の間の子のようなものです。

警告

xml.etree.ElementTree モジュールは悪意を持って構築されたデータに対して安全ではありません。信頼できないデータや認証されていないデータを解析する必要がある場合は、XML の脆弱性 を参照してください。

各要素は関連する多くのプロパティを持っています:

  • この要素がどういう種類のデータを表現しているかを同定する文字列であるタグ(別の言い方をすれば要素の型)
  • 幾つもの属性(Python 辞書に収められます)
  • テキスト文字列
  • オプションの末尾文字列
  • 幾つもの子要素(Python シーケンスに収められます)

element のインスタンスを作るには、 Element コンストラクタや SubElement() ファクトリー関数を使います。

ElementTree クラスは要素の構造を包み込み、それと XML を行き来するのに使えます。

この API の C 実装である xml.etree.cElementTree も使用可能です。

チュートリアルその他のドキュメントへのリンクについては http://effbot.org/zone/element-index.htm を参照して下さい。 Fredrik Lundh のページも xml.etree.ElementTree の開発バージョンの置き場所です。

バージョン 2.7 で変更: ElementTree API が 1.3 に更新されました。より詳しい情報については、 Introducing ElementTree 1.3 を参照してください。

19.7.1. チュートリアル

これは xml.etree.ElementTree (略して ET) を使用するための短いチュートリアルで、ブロックの構築およびモジュールの基本コンセプトを紹介することを目的としています。

19.7.1.1. XML 木構造と要素

XML は本質的に階層データ形式で、木構造で表すのが最も自然な方法です。ET はこの目的のために 2 つのクラス - XML 文書全体を木で表す ElementTree および木構造内の単一ノードを表す Element - を持っています。文書全体とのやりとり (ファイルの読み書き) は通常 ElementTree レベルで行います。単一 XML 要素およびその子要素とのやりとりは Element レベルで行います。

19.7.1.2. XML の解析

このセクションでは例として以下の XML 文書を使います:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank>1</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank>4</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank>68</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

データを取り込むのにはいくつかの方方があります。ディスクから読むにはこうします:

import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()

文字列から取り込むにはこうします:

root = ET.fromstring(country_data_as_string)

fromstring() は XML を文字列から Element に直接パースします。Element はパースされた木のルート要素です。他のパース関数は ElementTree を作成するかもしれません。ドキュメントをきちんと確認してください。

Element として、root はタグと属性の辞書を持ちます:

>>> root.tag
'data'
>>> root.attrib
{}

さらにイテレート可能な子ノードも持ちます:

>>> for child in root:
...     print child.tag, child.attrib
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}

子ノードは入れ子になっており、インデックスで子ノードを指定してアクセスできます:

>>> root[0][1].text
'2008'

19.7.1.3. 関心ある要素の検索

Element は、例えば、Element.iter() などの、配下 (その子ノードや孫ノードなど) の部分木全体を再帰的にイテレートするいくつかの役立つメソッドを持っています:

>>> for neighbor in root.iter('neighbor'):
...     print neighbor.attrib
...
{'name': 'Austria', 'direction': 'E'}
{'name': 'Switzerland', 'direction': 'W'}
{'name': 'Malaysia', 'direction': 'N'}
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}

Element.findall() はタグで現在の要素の直接の子要素のみ検索します。 Element.find() は特定のタグで 最初の 子要素を検索し、 Element.text は要素のテキストコンテンツにアクセスします。 Element.get() は要素の属性にアクセスします:

>>> for country in root.findall('country'):
...     rank = country.find('rank').text
...     name = country.get('name')
...     print name, rank
...
Liechtenstein 1
Singapore 4
Panama 68

XPath の使用は、検索したい要素を指定するより洗練された方法です。

19.7.1.4. XML ファイルの編集

ElementTree は XML 文書を構築してファイルに出力する簡単な方法を提供しています。ElementTree.write() メソッドはこの目的に適います。

Element オブジェクトを作成すると、そのフィールドの直接変更 (Element.text など) や、属性の追加および変更 (Element.set() メソッド)、あるいは新しい子ノードの追加 (例えば Element.append() など) によってそれを操作できます。

例えば各 country の rank に 1 を足して、rank 要素に updated 属性を追加したい場合:

>>> for rank in root.iter('rank'):
...     new_rank = int(rank.text) + 1
...     rank.text = str(new_rank)
...     rank.set('updated', 'yes')
...
>>> tree.write('output.xml')

XML はこのようになります:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank updated="yes">69</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Element.remove() を使って要素を削除することが出来ます。例えば rank が 50 より大きい全ての country を削除したい場合:

>>> for country in root.findall('country'):
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

XML はこのようになります:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
</data>

19.7.1.5. XML 文書の構築

SubElement() 関数は、与えられた要素に新しい子要素を作成する便利な手段も提供しています:

>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>

19.7.1.6. 名前空間のある XML の解析

If the XML input has namespaces, tags and attributes with prefixes in the form prefix:sometag get expanded to {uri}sometag where the prefix is replaced by the full URI. Also, if there is a default namespace, that full URI gets prepended to all of the non-prefixed tags.

ひとつは接頭辞 "fictional" でもうひとつがデフォルト名前空間で提供された、 2 つの名前空間を組み込んだ XML の例をここにお見せします:

<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
        xmlns="http://people.example.com">
    <actor>
        <name>John Cleese</name>
        <fictional:character>Lancelot</fictional:character>
        <fictional:character>Archie Leach</fictional:character>
    </actor>
    <actor>
        <name>Eric Idle</name>
        <fictional:character>Sir Robin</fictional:character>
        <fictional:character>Gunther</fictional:character>
        <fictional:character>Commander Clement</fictional:character>
    </actor>
</actors>

この XML の例を、検索し、渡り歩くためのひとつの方法としては、 find() や findall() に渡す xpath では全てのタグや属性に手作業で URI を付けてまわる手があります:

root = fromstring(xml_text)
for actor in root.findall('{http://people.example.com}actor'):
    name = actor.find('{http://people.example.com}name')
    print name.text
    for char in actor.findall('{http://characters.example.com}character'):
        print ' |-->', char.text

もっと良い方法があります。接頭辞の辞書を作り、これを検索関数で使うことです:

ns = {'real_person': 'http://people.example.com',
      'role': 'http://characters.example.com'}

for actor in root.findall('real_person:actor', ns):
    name = actor.find('real_person:name', ns)
    print name.text
    for char in actor.findall('role:character', ns):
        print ' |-->', char.text

どちらのアプローチでも同じ結果です:

John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement

19.7.1.7. その他の情報

http://effbot.org/zone/element-index.htm にはチュートリアルと他のドキュメントへのリンクがあります。

19.7.2. XPath サポート

このモジュールは木構造内の要素の位置決めのための XPath 表現 を限定的にサポートしています。その目指すところは短縮構文のほんの一部だけのサポートであり、XPath エンジンのフルセットは想定していません。

19.7.2.1. 例

以下はこのモジュールの XPath 機能の一部を紹介する例です。XML の解析 節から XML 文書 countrydata を使用します:

import xml.etree.ElementTree as ET

root = ET.fromstring(countrydata)

# Top-level elements
root.findall(".")

# All 'neighbor' grand-children of 'country' children of the top-level
# elements
root.findall("./country/neighbor")

# Nodes with name='Singapore' that have a 'year' child
root.findall(".//year/..[@name='Singapore']")

# 'year' nodes that are children of nodes with name='Singapore'
root.findall(".//*[@name='Singapore']/year")

# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")

19.7.2.2. サポートされている XPath 構文

操作 意味
tag 与えられたタグのすべての子要素を選択します。例えば、spam は spam と名付けられた子要素すべてを選択し、spam/egg は spam と名付けられた全子要素の中から egg と名付けられた孫要素をすべて選択します。
* すべての子要素を選択します。例えば、*/egg は egg と名付けられた孫要素をすべて選択します。
. 現在のノードを選択します。これはパスの先頭に置くことで相対パスであることを示すのに役立ちます。
// 現在の要素配下のすべてのレベル上のすべての子要素を選択します。例えば、.//egg は木全体から egg 要素を選択します。
.. 親要素を選択します。
[@attrib] 与えられた属性を持つすべての要素を選択します。
[@attrib='value'] 与えられた属性が、与えられた値を持つすべての要素を選択します。値に引用符が含まれてはなりません。
[tag] tag と名付けられた子要素を持つすべての要素を選択します。隣接した子要素のみサポートしています。
[tag='text'] 子孫を含む完全なテキストコンテンツと与えられた text が一致する、 tag と名付けられた子要素を持つすべての要素を選択します。
[position] 与えられた位置にあるすべての要素を選択します。位置は整数 (1 が先頭)、表現 last() (末尾)、あるいは末尾からの相対位置 (例: last()-1) のいずれかで指定できます。

述部 (角括弧内の表現) の前にはタグ名、アスタリスク、あるいはその他の述部がなければなりません。position 述部の前にはタグ名がなければなりません。

19.7.3. リファレンス

19.7.3.1. 関数

xml.etree.ElementTree.Comment(text=None)

コメント要素のファクトリです。このファクトリ関数は、標準のシリアライザでは XML コメントにシリアライズされる特別な要素を作ります。コメント文字列はバイト文字列でも Unicode 文字列でも構いません。text はそのコメント文字列を含んだ文字列です。コメントを表わす要素のインスタンスを返します。

xml.etree.ElementTree.dump(elem)

要素の木もしくは要素の構造を sys.stdout に出力します。この関数はデバッグ目的のみに使用してください。

出力される形式の正確なところは実装依存です。このバージョンでは、通常の XML ファイルとして出力されます。

elem は要素の木もしくは個別の要素です。

xml.etree.ElementTree.fromstring(text)

文字列定数で与えられた XML 断片を解析します。 XML() 関数と同じです。 text は XML データの文字列です。 Element インスタンスを返します。

xml.etree.ElementTree.fromstringlist(sequence, parser=None)

文字列フラグメントのシーケンスから XML ドキュメントを解析します。 sequence は XML データのフラグメントを格納した、リストかその他のシーケンスです。 parser はオプションのパーザインスタンスです。パーザが指定されない場合、標準の XMLParser パーザが使用されます。 Element インスタンスを返します。

バージョン 2.7 で追加.

xml.etree.ElementTree.iselement(element)

オブジェクトが正当な要素オブジェクトであるかをチェックします。 element は要素インスタンスです。引数が要素オブジェクトならば真値を返します。

xml.etree.ElementTree.iterparse(source, events=None, parser=None)

XML 断片を構文解析して要素の木を漸増的に作っていき、その間進行状況をユーザーに報告します。 source は XML データを含むファイル名またはファイル風オブジェクト。 events は報告すべきイベントのリスト。省略された場合は "end" イベントだけが報告されます。 parser はオプションの引数で、パーサーのインスタンスを指定します。指定されなかった場合は標準の XMLParser が利用されます。 parser は cElementTree ではサポートされていません。 (event, elem) ペアのイテレータ(iterator)を返します。

注釈

iterparse() は "start" イベントを発行した時に開始タグの文字 ">" が現れたことだけを保証します。そのため、属性は定義されますが、その時点ではテキストの内容も tail 属性も定義されていません。同じことは子要素にも言えて、その時点ではあるともないとも言えません。

全部揃った要素が必要ならば、"end" イベントを探してください。

xml.etree.ElementTree.parse(source, parser=None)

XML 断片を解析して要素の木にします。 source には XML データを含むファイル名またはファイルオブジェクトを指定します。 parser はオプションでパーザインスタンスを指定します。パーザが指定されない場合、標準の XMLParser パーザが使用されます。 ElementTree インスタンスを返します。

xml.etree.ElementTree.ProcessingInstruction(target, text=None)

PI 要素のファクトリです。このファクトリ関数は XML の処理命令としてシリアライズされた特別な要素を作成します。target は PI ターゲットを含んだ文字列です。text を指定する場合は PI コンテンツを含む文字列にします。PI を表わす要素インスタンスを返します。

xml.etree.ElementTree.register_namespace(prefix, uri)

名前空間の接頭辞を登録します。レジストリはグローバルで、与えられた接頭辞か名前空間 URI のどちらかの既存のマッピングはすべて削除されます。prefix には名前空間の接頭辞を指定します。uri には名前空間の URI を指定します。この名前空間のタグや属性は、可能な限り与えられた接頭辞をつけてシリアライズされます。

バージョン 2.7 で追加.

xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)

子要素のファクトリです。この関数は要素インスタンスを作成し、それを既存の要素に追加します。

要素名、属性名、および属性値はバイト文字列でも Unicode 文字列でも構いません。 parent には親要素を指定します。 tag には要素名を指定します。attrib はオプションで要素の属性を含む辞書を指定します。 extra は追加の属性で、キーワード引数として与えます。要素インスタンスを返します。

xml.etree.ElementTree.tostring(element, encoding="us-ascii", method="xml")

XML 要素を全ての子要素を含めて表現する文字列を生成します。 element は Element のインスタンスです。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。 method は "xml", "html", "text" のいずれか(デフォルトは "xml") です。 XML データを含んだエンコードされた文字列を返します。

xml.etree.ElementTree.tostringlist(element, encoding="us-ascii", method="xml")

XML 要素を全ての子要素を含めて表現する文字列を生成します。 element は Element のインスタンスです。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。 method は "xml", "html", "text" のいずれか(デフォルトは "xml") です。 XML データを含んだエンコードされた文字列のリストを返します。これは、 "".join(tostringlist(element)) == tostring(element) であること以外、なにか特定のシーケンスになることは保証していません。

バージョン 2.7 で追加.

xml.etree.ElementTree.XML(text, parser=None)

文字列定数で与えられた XML 断片を解析します。この関数は Python コードに "XML リテラル" を埋め込むのに使えます。 text には XML データを含む文字列を指定します。 parser はオプションで、パーザのインスタンスを指定します。指定されなかった場合、標準の XMLParser パーザを使用します。 Element インスタンスを返します。

xml.etree.ElementTree.XMLID(text, parser=None)

文字列定数で与えられた XML 断片を解析し、要素 ID と要素を対応付ける辞書を返します。 text には XMLデータを含んだ文字列を指定します。 parser はオプションで、パーザのインスタンスを指定します。指定されなかった場合、標準の XMLParser パーザを使用します。 Element のインスタンスと辞書のタプルを返します。

19.7.3.2. Element オブジェクト

class xml.etree.ElementTree.Element(tag, attrib={}, **extra)

要素クラスです。この関数は Element インタフェースを定義すると同時に、そのリファレンス実装を提供します。

要素名、属性名、および属性値はバイト文字列でも Unicode 文字列でも構いません。 tag には要素名を指定します。attrib はオプションで、要素と属性を含む辞書を指定します。extra は追加の属性で、キーワード引数として与えます。要素インスタンスを返します。

tag

この要素が表すデータの種類を示す文字列です (言い替えると、要素の型です)。

text
tail

これらの属性は要素に結びつけられた付加的なデータを保持するのに使われます。これらの属性値はたいてい文字列ですが、アプリケーション固有のオブジェクトであって構いません。要素が XML ファイルから作られる場合、 text 属性は要素の開始タグとその最初の子要素または終了タグまでのテキストか、あるいは None を保持し、 tail 属性は要素の終了タグと次のタグまでのテキストか、あるいは None を保持します。このような XML データ

<a><b>1<c>2<d/>3</c></b>4</a>

の場合、 a 要素は text, tail 属性ともに None, b 要素は text に "1" で tail に "4", c 要素は text に "2" で tail は None, d 要素 は text が None で tail に "3" をそれぞれ保持します。

要素の内側のテキストを収集するためには、itertext() を参照してください。例えば "".join(element.itertext()) のようにします。

アプリケーションはこれらの属性に任意のオブジェクトを格納できます。

attrib

要素の属性を保持する辞書です。 attrib の値は常に書き換え可能な Python 辞書ですが、ElementTree の実装によっては別の内部表現を使用し、要求されたときにだけ辞書を作るようにしているかもしれません。そうした実装の利益を享受するために、可能な限り下記の辞書メソッドを通じて使用してください。

以下の辞書風メソッドが要素の属性に対して動作します。

clear()

要素をリセットします。この関数は全ての子要素を削除し、全属性を消去し、テキストとテール属性を None に設定します。

get(key, default=None)

要素の key という名前の属性を取得します。

属性の値、または属性がない場合は default を返します。

items()

要素の属性を (名前, 値) ペアのシーケンスとして返します。返される属性の順番は決まっていません。

keys()

要素の属性名をリストとして返します。返される名前の順番は決まっていません。

set(key, value)

要素の属性 key に value をセットします。

以下のメソッドは要素の子要素 (副要素) に対して動作します。

append(subelement)

要素 subelement をこの要素の内部にあるサブ要素のリストの最後に追加します。

extend(subelements)

シーケンスオブジェクト subelements から 0個以上のサブ要素を追加します。サブ要素が有効なオブジェクトでない場合は AssertionError を発生させます。

バージョン 2.7 で追加.

find(match)

match にマッチする最初のサブ要素を探します。 match はタグ名かパス(path)です。要素・インスタンスまたは None を返します。

findall(match)

タグ名かパスにマッチする全てのサブ要素を探します。全てのマッチする要素を、ドキュメント上の順序で含むリストを返します。

findtext(match, default=None)

match にマッチする最初のサブ要素のテキストを探します。 match はタグ名かパスです。最初にマッチする要素の text を返すか、要素が見あたらなかった場合 default を返します。マッチした要素に text がなければ空文字列が返されるので気を付けましょう。

getchildren()

バージョン 2.7 で撤廃: list(elem) かイテレーションを使用してください。

getiterator(tag=None)

バージョン 2.7 で撤廃: 代わりに Element.iter() メソッドを使用してください。

insert(index, element)

サブ要素をこの要素の与えられた位置に挿入します。

iter(tag=None)

現在の要素を根とする木の イテレータ を作成します。イテレータは現在の要素とそれ以下のすべての要素を、文書内での出現順 (深さ優先順) でイテレートします。 tag が None または '*' でない場合、与えられたタグに等しいものについてのみイテレータから返されます。イテレート中に木構造が変更された場合の結果は未定義です。

バージョン 2.7 で追加.

iterfind(match)

タグ名かパスにマッチする全てのサブ要素を探します。全てのマッチする要素をドキュメント上の順序で yield するイテレート可能オブジェクトを返します。

バージョン 2.7 で追加.

itertext()

テキストのイテレータを作成します。イテレータは、この要素とすべての子要素を文書上の順序で巡回し、すべての内部のテキストを返します。

バージョン 2.7 で追加.

makeelement(tag, attrib)

現在の要素と同じ型の新しい要素オブジェクトを作成します。このメソッドは呼び出さずに、 SubElement() ファクトリ関数を使って下さい。

remove(subelement)

要素から subelement を削除します。find* メソッド群と異なり、このメソッドは要素をインスタンスの同一性で比較します。タグや内容では比較しません。

Element オブジェクトは以下のシーケンス型のメソッドを、サブ要素を操作するためにサポートします: object:__delitem__(), object:__getitem__(), object:__setitem__(), object:__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"

19.7.3.3. ElementTree オブジェクト

class xml.etree.ElementTree.ElementTree(element=None, file=None)

ElementTree ラッパークラスです。このクラスは要素の全階層を表現し、さらに標準 XML との相互変換を追加しています。

element は根要素です。木は file が与えられればその XML の内容により初期化されます。

_setroot(element)

この木の根要素を置き換えます。従って現在の木の内容は破棄され、与えられた要素が代わりに使われます。注意して使ってください。 element は要素インスタンスです。

find(match)

Element.find() と同じで、木の根要素を起点とします。

findall(match)

Element.findall() と同じで、木の根要素を起点とします。

findtext(match, default=None)

Element.findtext() と同じで、木の根要素を起点とします。

getiterator(tag=None)

バージョン 2.7 で撤廃: 代わりに ElementTree.iter() メソッドを使用してください。

getroot()

この木のルート要素を返します。

iter(tag=None)

根要素に対する、木を巡回するイテレータを返します。イテレータは木のすべての要素に渡ってセクション順にループします。tag は探したいタグです (デフォルトではすべての要素を返します)。

iterfind(match)

タグ名かパスにマッチする全てのサブ要素を返します。 getroot().iterfind(match) と同じです。全てのマッチする要素をドキュメント順に yield するイテレート可能オブジェクトを返します。

バージョン 2.7 で追加.

parse(source, parser=None)

外部の XML 断片をこの要素の木に読み込みます。 source は XML データを含むファイル名またはファイル風オブジェクト。 parser はオプションの構文解析器インスタンスです。これが与えられない場合、標準の XMLParser パーサーが使われます。断片の根要素を返します。

write(file, encoding="us-ascii", xml_declaration=None, default_namespace=None, method="xml")

要素の木をファイルに XML として書き込みます。 file はファイル名またはファイル風オブジェクトで書き込み用に開かれたもの。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。 xml_declaration は、 XML 宣言がファイルに書かれるかどうかを制御します。 False の場合は常に書かれず、 True の場合は常に書かれ、 None の場合は US-ASCII か UTF-8 以外の場合に書かれます (デフォルトは None です)。 default_namespace でデフォルトの XML 名前空間 ("xmlns" 用) を指定します。 method は "xml", "html", "text" のいづれかです (デフォルトは "xml" です)。エンコードされた文字列を返します。

以下はこれから操作する XML ファイルです:

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>Moved to <a href="http://example.org/">example.org</a>
        or <a href="http://example.com/">example.com</a>.</p>
    </body>
</html>

第 1 段落のすべてのリンクの "target" 属性を変更する例:

>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a"))   # Returns list of all links
>>> links
[<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")

19.7.3.4. QName オブジェクト

class xml.etree.ElementTree.QName(text_or_uri, tag=None)

QName ラッパーです。このクラスは QName 属性値をラップし、出力時に適切な名前空間の扱いを得るために使われます。 text_or_uri は {uri}local という形式の QName 値を含む文字列、または tag 引数が与えられた場合には QName の URI 部分の文字列です。 tag が与えられた場合、一つめの引数は URI と解釈され、この引数はローカル名と解釈されます。 QName インスタンスは不透明です。

19.7.3.5. TreeBuilder オブジェクト

class xml.etree.ElementTree.TreeBuilder(element_factory=None)

汎用の要素構造ビルダー。これは start, data, end のメソッド呼び出しの列を整形式の要素構造に変換します。このクラスを使うと、好みの XML 構文解析器、または他の XML に似た形式の構文解析器を使って、要素構造を作り出すことができます。 element_factory が与えられた場合には、新しい Element インスタンスを作る際にこれを呼び出します。

close()

ビルダのバッファをフラッシュし、最上位の文書要素を返します。戻り値は Element インスタンスになります。

data(data)

現在の要素にテキストを追加します。 data は文字列です。バイト文字列もしくは Unicode 文字列でなければなりません。

end(tag)

現在の要素を閉じます。 tag は要素の名前です。閉じられた要素を返します。

start(tag, attrs)

新しい要素を開きます。 tag は要素の名前です。 attrs は要素の属性を保持した辞書です。開かれた要素を返します。

加えて、カスタムの TreeBuilder オブジェクトは以下のメソッドを提供できます:

doctype(name, pubid, system)

doctype 宣言を処理します。 name は doctype 名です。 pubid は公式の識別子です。 system はシステム識別子です。このメソッドはデフォルトの TreeBuilder クラスには存在しません。

バージョン 2.7 で追加.

19.7.3.6. XMLParser オブジェクト

class xml.etree.ElementTree.XMLParser(html=0, target=None, encoding=None)

expat パーサーを利用した、XML ソースデータからの Element 構造ビルダー。 html は定義済みの HTML エンティティです。このフラグは現在の実装ではサポートされていません。 target はターゲットオブジェクトです。省略された場合、ビルダーは標準の TreeBuilder クラスのインスタンスを利用します。 encoding [1] はオプションで、与えられた場合は XML ファイルで指定されたエンコーディングをオーバーライドします。

close()

構文解析器にデータを供給するのを終わりにします。要素構造を返します。

doctype(name, pubid, system)

バージョン 2.7 で撤廃: カスタムの TreeBuilder target で TreeBuilder.doctype() メソッドを定義してください。

feed(data)

パーザへデータを入力します。 data はエンコードされたデータです。

XMLParser.feed() は target の start() メソッドをそれぞれの開始タグに対して呼び、また end() メソッドを終了タグに対して呼び、そしてデータは data() メソッドで処理されます。 XMLParser.close() は target の close() メソッドを呼びます。 XMLParser は木構造を構築する以外にも使えます。以下の例は、XML ファイルの最高の深さを数えます:

>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth:                     # The target object of the parser
...     maxDepth = 0
...     depth = 0
...     def start(self, tag, attrib):   # Called for each opening tag.
...         self.depth += 1
...         if self.depth > self.maxDepth:
...             self.maxDepth = self.depth
...     def end(self, tag):             # Called for each closing tag.
...         self.depth -= 1
...     def data(self, data):
...         pass            # We do not need to do anything with data.
...     def close(self):    # Called when all data has been parsed.
...         return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
...   <b>
...   </b>
...   <b>
...     <c>
...       <d>
...       </d>
...     </c>
...   </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4

注記

[1](1, 2, 3, 4) XML 出力に含まれるエンコーディング文字列は適切な規格に従っていなければなりません。例えば、"UTF-8" は有効ですが、"UTF8" はそうではありません。https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl と https://www.iana.org/assignments/character-sets/character-sets.xhtml を参照してください。