20.5. `xml.etree.ElementTree` — ElementTree XML API¶

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

xml.etree.ElementTree モジュールは、XML データを解析および作成するシンプルかつ効率的な API を実装しています。

バージョン 3.3 で変更: このモジュールは利用出来る場合は常に高速な実装を使用します。xml.etree.cElementTree は非推奨です。

警告

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

20.5.1. チュートリアル¶

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

20.5.1.1. XML 木構造と要素¶

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

20.5.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'

注釈

Not all elements of the XML input will end up as elements of the parsed tree. Currently, this module skips over any XML comments, processing instructions, and document type declarations in the input. Nevertheless, trees built using this module’s API rather than parsing from XML text can have comments and processing instructions in them; they will be included when generating XML output. A document type declaration may be accessed by passing a custom TreeBuilder instance to the XMLParser constructor.

20.5.1.3. Pull API for non-blocking parsing¶

Most parsing functions provided by this module require the whole document to be read at once before returning any result. It is possible to use an XMLParser and feed data into it incrementally, but it is a push API that calls methods on a callback target, which is too low-level and inconvenient for most needs. Sometimes what the user really wants is to be able to parse XML incrementally, without blocking operations, while enjoying the convenience of fully constructed Element objects.

The most powerful tool for doing this is XMLPullParser. It does not require a blocking read to obtain the XML data, and is instead fed with data incrementally with XMLPullParser.feed() calls. To get the parsed XML elements, call XMLPullParser.read_events(). Here is an example:

>>> parser = ET.XMLPullParser(['start', 'end'])
>>> parser.feed('<mytag>sometext')
>>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> parser.feed(' more text</mytag>')
>>> for event, elem in parser.read_events():
...     print(event)
...     print(elem.tag, 'text=', elem.text)
...
end

The obvious use case is applications that operate in a non-blocking fashion where the XML data is being received from a socket or read incrementally from some storage device. In such cases, blocking reads are unacceptable.

Because it’s so flexible, XMLPullParser can be inconvenient to use for simpler use-cases. If you don’t mind your application blocking on reading XML data but would still like to have incremental parsing capabilities, take a look at iterparse(). It can be useful when you’re reading a large XML document and don’t want to hold it wholly in memory.

20.5.1.4. 関心ある要素の検索¶

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 の使用は、検索したい要素を指定するより洗練された方法です。

20.5.1.5. 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>

20.5.1.6. 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>

20.5.1.7. 名前空間のある 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

20.5.1.8. その他の情報¶

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

20.5.2. XPath サポート¶

This module provides limited support for XPath expressions for locating elements in a tree. The goal is to support a small subset of the abbreviated syntax; a full XPath engine is outside the scope of the module.

20.5.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]")

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

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

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

20.5.3. リファレンス¶

20.5.3.1. 関数¶

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

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

Note that XMLParser skips over comments in the input instead of creating comment objects for them. An ElementTree will only contain comment nodes if they have been inserted into to the tree using one of the Element methods.

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 インスタンスを返します。

バージョン 3.2 で追加.

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

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

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 sequence of events to report back. The supported events are the strings "start", "end", "start-ns" and "end-ns" (the “ns” events are used to get detailed namespace information). If events is omitted, only "end" events are reported. parser is an optional parser instance. If not given, the standard XMLParser parser is used. parser must be a subclass of XMLParser and can only use the default TreeBuilder as a target. Returns an iterator providing (event, elem) pairs.

Note that while iterparse() builds the tree incrementally, it issues blocking reads on source (or the file it names). As such, it’s unsuitable for applications where blocking reads can’t be made. For fully non-blocking parsing, see XMLPullParser.

注釈

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

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

バージョン 3.4 で撤廃: parser 引数。

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 を表わす要素インスタンスを返します。

Note that XMLParser skips over processing instructions in the input instead of creating comment objects for them. An ElementTree will only contain processing instruction nodes if they have been inserted into to the tree using one of the Element methods.

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

バージョン 3.2 で追加.

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

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

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

xml.etree.ElementTree.tostring(element, encoding="us-ascii", method="xml", *, short_empty_elements=True)¶: Generates a string representation of an XML element, including all subelements. element is an Element instance. encoding [1] is the output encoding (default is US-ASCII). Use encoding="unicode" to generate a Unicode string (otherwise, a bytestring is generated). method is either "xml", "html" or "text" (default is "xml"). short_empty_elements has the same meaning as in ElementTree.write(). Returns an (optionally) encoded string containing the XML data.

バージョン 3.4 で追加: short_empty_elements 引数。

xml.etree.ElementTree.tostringlist(element, encoding="us-ascii", method="xml", *, short_empty_elements=True)¶: Generates a string representation of an XML element, including all subelements. element is an Element instance. encoding [1] is the output encoding (default is US-ASCII). Use encoding="unicode" to generate a Unicode string (otherwise, a bytestring is generated). method is either "xml", "html" or "text" (default is "xml"). short_empty_elements has the same meaning as in ElementTree.write(). Returns a list of (optionally) encoded strings containing the XML data. It does not guarantee any specific sequence, except that b"".join(tostringlist(element)) == tostring(element).

バージョン 3.2 で追加.

バージョン 3.4 で追加: short_empty_elements 引数。

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 のインスタンスと辞書のタプルを返します。

20.5.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 を、要素の子要素の内部リストの末尾に追加します。subelement Element でない場合、TypeError を送出します。

extend(subelements)¶: 0 個以上の要素のシーケンスオブジェクトによって subelements を拡張します。subelements が Element でない場合、TypeError を送出します。

バージョン 3.2 で追加.

find(match, namespaces=None)¶: match にマッチする最初の子要素を検索します。match はタグ名またはパスを指定できます。要素インスタンスか None を返します。namespaces はオプションで、名前空間接頭辞から完全名を対応付けるマップオブジェクトを指定します。

findall(match, namespaces=None)¶: タグ名またはパスにマッチするすべての子要素を検索します。マッチしたすべての子要素が文書内の順序で含まれたリストを返します。namespaces はオプションで、名前空間接頭辞から完全名を対応付けるマップオブジェクトを指定します。

findtext(match, default=None, namespaces=None)¶: match にマッチする最初の子要素のテキストを検索します。match にはタグ名またはパスを指定できます。最初にマッチした要素の内容のテキストを返します。マッチする要素が無い場合 default を返します。マッチした要素の内容にテキストがなかった場合空の文字列が返ります。namespaces はオプションで、名前空間接頭辞から完全名を対応付けるマップオブジェクトを指定します。

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

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

insert(index, subelement)¶: 要素内の指定された位置に subelement を挿入します。subelement が Element でない場合、TypeError を送出します。

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

バージョン 3.2 で追加.

iterfind(match, namespaces=None)¶: タグ名またはパスにマッチするすべての子要素を検索します。マッチしたすべての要素を文書内での出現順で yield するイテレータを返します。namespaces はオプションで、名前空間接頭辞と完全名を対応付けるマップオブジェクトを指定します。

バージョン 3.2 で追加.

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

バージョン 3.2 で追加.

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

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

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

20.5.3.3. ElementTree オブジェクト¶

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

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

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

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

find(match, namespaces=None)¶: Element.find() と同じで、木の根要素を起点とします。

findall(match, namespaces=None)¶: Element.findall() と同じで、木の根要素を起点とします。

findtext(match, default=None, namespaces=None)¶: Element.findtext() と同じで、木の根要素を起点とします。

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

getroot()¶: この木のルート要素を返します。

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

iterfind(match, namespaces=None)¶: Element.iterfind() と同じで、木の根要素を起点とします。

バージョン 3.2 で追加.

parse(source, parser=None)¶: 外部の XML 断片をこの要素木に入れます。source にはファイル名かファイルオブジェクトを指定します。parser はオプションで、パーザインスタンスを指定します。パーザが指定されない場合、標準の XMLParser パーザが使用されます。断片の根要素を返します。

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

Writes the element tree to a file, as XML. file is a file name, or a file object opened for writing. encoding [1] is the output encoding (default is US-ASCII). xml_declaration controls if an XML declaration should be added to the file. Use False for never, True for always, None for only if not US-ASCII or UTF-8 or Unicode (default is None). default_namespace sets the default XML namespace (for “xmlns”). method is either "xml", "html" or "text" (default is "xml"). The keyword-only short_empty_elements parameter controls the formatting of elements that contain no content. If True (the default), they are emitted as a single self-closed tag, otherwise they are emitted as a pair of start/end tags.

出力は引数 encoding によって、文字列 (str) かバイト列 (bytes) になります。encoding が "unicode" の場合、出力は文字列になり、それ以外ではバイト列になります。file がファイルオブジェクトの場合、型が衝突する場合があります。文字列をバイト列ファイルへ書き込んだり、その逆を行わないよう注意してください。

バージョン 3.4 で追加: short_empty_elements 引数。

以下はこれから操作する 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")

20.5.3.4. QName オブジェクト¶

class xml.etree.ElementTree.QName(text_or_uri, tag=None)¶: QName wrapper. This can be used to wrap a QName attribute value, in order to get proper namespace handling on output. text_or_uri is a string containing the QName value, in the form {uri}local, or, if the tag argument is given, the URI part of a QName. If tag is given, the first argument is interpreted as a URI, and this argument is interpreted as a local name. QName instances are opaque.

20.5.3.5. TreeBuilder オブジェクト¶

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

汎用の要素構造ビルダです。これは start、data、および end メソッドのシーケンスを適格な要素構造に変換します。このクラスを使うと、カスタム XML パーザ、あるいは他の XML に似た形式のパーザを使用して要素構造を構築できます。element_factory を指定する場合、タグと属性の辞書の 2 個の位置引数へのアクセスによって呼び出し可能でなければなりません。これは新しい要素インスタンスを返すはずです。

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 クラスには存在しません。

バージョン 3.2 で追加.

20.5.3.6. XMLParser オブジェクト¶

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

This class is the low-level building block of the module. It uses xml.parsers.expat for efficient, event-based parsing of XML. It can be fed XML data incrementally with the feed() method, and parsing events are translated to a push API - by invoking callbacks on the target object. If target is omitted, the standard TreeBuilder is used. The html argument was historically used for backwards compatibility and is now deprecated. If encoding [1] is given, the value overrides the encoding specified in the XML file.

バージョン 3.4 で撤廃: The html argument. The remaining arguments should be passed via keyword to prepare for the removal of the html argument.

close()¶: Finishes feeding data to the parser. Returns the result of calling the close() method of the target passed during construction; by default, this is the toplevel document element.

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

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

XMLParser.feed() calls target‘s start(tag, attrs_dict) method for each opening tag, its end(tag) method for each closing tag, and data is processed by method data(data). XMLParser.close() calls target‘s method close(). XMLParser can be used not only for building a tree structure. This is an example of counting the maximum depth of an XML file:

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

20.5.3.7. XMLPullParser オブジェクト¶

class xml.etree.ElementTree.XMLPullParser(events=None)¶

A pull parser suitable for non-blocking applications. Its input-side API is similar to that of XMLParser, but instead of pushing calls to a callback target, XMLPullParser collects an internal list of parsing events and lets the user read from it. events is a sequence of events to report back. The supported events are the strings "start", "end", "start-ns" and "end-ns" (the “ns” events are used to get detailed namespace information). If events is omitted, only "end" events are reported.

feed(data)¶: Feed the given bytes data to the parser.

close()¶: Signal the parser that the data stream is terminated. Unlike XMLParser.close(), this method always returns None. Any events not yet retrieved when the parser is closed can still be read with read_events().

read_events()¶

Return an iterator over the events which have been encountered in the data fed to the parser. The iterator yields (event, elem) pairs, where event is a string representing the type of event (e.g. "end") and elem is the encountered Element object.

Events provided in a previous call to read_events() will not be yielded again. Events are consumed from the internal queue only when they are retrieved from the iterator, so multiple readers iterating in parallel over iterators obtained from read_events() will have unpredictable results.

注釈

XMLPullParser は “start” イベントを発行した時に開始タグの文字 “>” が現れたことだけを保証します。そのため、属性は定義されますが、その時点ではテキストの内容も tail 属性も定義されていません。子要素にもそれが存在する、しないにかかわらず同じ物が適用されます。

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

バージョン 3.4 で追加.

20.5.3.8. 例外¶

class xml.etree.ElementTree.ParseError¶

解析に失敗した時、このモジュールの様々なメソッドから送出される XML 解析エラーです。この例外のインスタンスが表す文字列は、ユーザフレンドリなメッセージを含んでいます。その他に、以下の属性も利用できます:

code¶: expat パーザからの数値エラーコードです。エラーコードの一覧とそれらの意味については、xml.parsers.expat のドキュメントを参照してください。

position¶: エラーが発生した場所を示す line と column 番号のタプルです。

脚注

[1]	The encoding string included in XML output should conform to the appropriate standards. For example, “UTF-8” is valid, but “UTF8” is not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and https://www.iana.org/assignments/character-sets/character-sets.xhtml.

20.5. `xml.etree.ElementTree` — ElementTree XML API¶

20.5.1. チュートリアル¶

20.5.1.1. XML 木構造と要素¶

20.5.1.2. XML の解析¶

20.5.1.3. Pull API for non-blocking parsing¶

20.5.1.4. 関心ある要素の検索¶

20.5.1.5. XML ファイルの編集¶

20.5.1.6. XML 文書の構築¶

20.5.1.7. 名前空間のある XML の解析¶

20.5.1.8. その他の情報¶

20.5.2. XPath サポート¶

20.5.2.1. 例¶

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

20.5.3. リファレンス¶

20.5.3.1. 関数¶

20.5.3.2. Element オブジェクト¶

20.5.3.3. ElementTree オブジェクト¶

20.5.3.4. QName オブジェクト¶

20.5.3.5. TreeBuilder オブジェクト¶

20.5.3.6. XMLParser オブジェクト¶

20.5.3.7. XMLPullParser オブジェクト¶

20.5.3.8. 例外¶

目次

前のトピックへ

次のトピックへ

このページ

20.5. xml.etree.ElementTree — ElementTree XML API¶

20.5.1. チュートリアル¶

20.5.1.1. XML 木構造と要素¶

20.5.1.2. XML の解析¶

20.5.1.3. Pull API for non-blocking parsing¶

20.5.1.4. 関心ある要素の検索¶

20.5.1.5. XML ファイルの編集¶

20.5.1.6. XML 文書の構築¶

20.5.1.7. 名前空間のある XML の解析¶

20.5.1.8. その他の情報¶

20.5.2. XPath サポート¶

20.5.2.1. 例¶

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

20.5.3. リファレンス¶

20.5.3.1. 関数¶

20.5.3.2. Element オブジェクト¶

20.5.3.3. ElementTree オブジェクト¶

20.5.3.4. QName オブジェクト¶

20.5.3.5. TreeBuilder オブジェクト¶

20.5.3.6. XMLParser オブジェクト¶

20.5.3.7. XMLPullParser オブジェクト¶

20.5.3.8. 例外¶

20.5. `xml.etree.ElementTree` — ElementTree XML API¶