xml.etree.ElementTree — ElementTree XML API

ソースコード： ：source： `Lib / xml / etree / ElementTree.py`

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

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

警告

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

チュートリアル

これは、 xml.etree.ElementTree （略してET）を使用するための短いチュートリアルです。目標は、モジュールの構成要素と基本概念のいくつかを示すことです。

XMLツリーと要素

XMLは本質的に階層的なデータ形式であり、XMLを表現する最も自然な方法はツリーを使用することです。 ETには、この目的のために2つのクラスがあります。 ElementTree はXMLドキュメント全体をツリーとして表し、 Element はこのツリーの単一ノードを表します。ドキュメント全体とのやり取り（ファイルの読み取りと書き込み）は通常、 ElementTree レベルで行われます。単一のXML要素とそのサブ要素との相互作用は、 Element レベルで行われます。

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 に解析します。これは、解析されたツリーのルート要素です。他の解析関数は、 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'

ノート

XML入力のすべての要素が、解析されたツリーの要素になるわけではありません。現在、このモジュールは、入力内のXMLコメント、処理命令、および文書型宣言をスキップします。それでも、XMLテキストから解析するのではなく、このモジュールのAPIを使用して構築されたツリーには、コメントと処理命令を含めることができます。これらは、XML出力を生成するときに含まれます。文書型宣言には、カスタム TreeBuilder インスタンスを XMLParser コンストラクターに渡すことでアクセスできます。

ノンブロッキング解析用のプルAPI

このモジュールが提供するほとんどの解析関数では、結果を返す前にドキュメント全体を一度に読み取る必要があります。 XMLParser を使用してデータを段階的にフィードすることは可能ですが、これはコールバックターゲットのメソッドを呼び出すプッシュAPIであり、低レベルであり、ほとんどのニーズには不便です。ユーザーが本当に望んでいるのは、完全に構築された Element オブジェクトの利便性を享受しながら、操作をブロックすることなくXMLを段階的に解析できることです。

これを行うための最も強力なツールは XMLPullParser です。 XMLデータを取得するためにブロッキング読み取りを必要とせず、代わりに XMLPullParser.feed（）呼び出しでデータが段階的に供給されます。解析されたXML要素を取得するには、 XMLPullParser.read_events（）を呼び出します。次に例を示します。

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

明らかな使用例は、XMLデータがソケットから受信されるか、一部のストレージデバイスから段階的に読み取られる非ブロッキング方式で動作するアプリケーションです。このような場合、読み取りのブロックは受け入れられません。

XMLPullParser は非常に柔軟性があるため、単純なユースケースでの使用には不便な場合があります。 XMLデータの読み取りでアプリケーションがブロックされてもかまわないが、インクリメンタル解析機能が必要な場合は、 iterparse（）を参照してください。大きなXMLドキュメントを読んでいて、それを完全にメモリに保持したくない場合に便利です。

興味深い要素を見つける

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（）は、特定のタグを持つ first の子を検索し、 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 を使用すると、検索する要素をより高度に指定できます。

XMLファイルの変更

ElementTree は、XMLドキュメントを作成してファイルに書き込む簡単な方法を提供します。 ElementTree.write（）メソッドはこの目的を果たします。

作成された Element オブジェクトは、そのフィールド（ Element.text など）を直接変更したり、属性を追加および変更したり（ Element.set（））することで操作できます。メソッド）、および新しい子の追加（たとえば、 Element.append（）を使用）。

各国のランクに1つ追加し、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（）を使用して要素を削除できます。ランクが50を超えるすべての国を削除するとします。

>>> for country in root.findall('country'):
...     # using root.findall() to avoid removal during traversal
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

反復中の同時変更は、Pythonリストまたはdictを反復および変更する場合と同様に、問題を引き起こす可能性があることに注意してください。したがって、この例では、最初にroot.findall()で一致するすべての要素を収集してから、一致するリストを繰り返し処理します。

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>

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>

名前空間を使用したXMLの解析

XML入力に名前空間がある場合、prefix:sometagの形式のプレフィックスを持つタグと属性は{uri}sometagに展開され、プレフィックスは完全なものに置き換えられます URI 。また、デフォルトの名前空間がある場合、その完全なURIがプレフィックスなしのすべてのタグの前に付加されます。

これは、2つの名前空間を組み込んだXMLの例です。1つは接頭辞「架空」で、もう1つはデフォルトの名前空間として機能します。

<?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の例を検索して探索する1つの方法は、 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)

名前空間付きXMLの例を検索するためのより良い方法は、独自のプレフィックスを使用して辞書を作成し、それらを検索関数で使用することです。

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)

これらの2つのアプローチは両方とも出力します：

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

追加のリソース

チュートリアルと他のドキュメントへのリンクについては、 http://effbot.org/zone/element-index.htmを参照してください。

XPathサポート

このモジュールは、ツリー内の要素を見つけるための XPath式の限定的なサポートを提供します。目標は、省略された構文の小さなサブセットをサポートすることです。完全なXPathエンジンは、モジュールの範囲外です。

例

これは、モジュールのXPath機能の一部を示す例です。 Parsing XML セクションのcountrydata XMLドキュメントを使用します。

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

名前空間を持つXMLの場合、通常の修飾された{namespace}tag表記を使用します。

# All dublin-core "title" tags in the document
root.findall(".//{http://purl.org/dc/elements/1.1/}title")

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

構文	意味
`tag`	指定されたタグを持つすべての子要素を選択します。たとえば、`spam`は`spam`という名前のすべての子要素を選択し、`spam/egg`は`spam`という名前のすべての子から`egg`という名前のすべての孫を選択します。 `{namespace}`は指定された名前空間のすべてのタグを選択し、`{}spam`は任意の（またはまったく）名前空間の`spam`という名前のタグを選択し、`{}*`はそうでないタグのみを選択します名前空間で。バージョン3.8で変更：スターワイルドカードのサポートが追加されました。
`*`	コメントや処理命令を含む、すべての子要素を選択します。たとえば、`*/egg`は、`egg`という名前のすべての孫を選択します。
`.`	現在のノードを選択します。これは、パスの先頭で、相対パスであることを示すのに最も役立ちます。
`//`	現在の要素の下のすべてのレベルで、すべてのサブ要素を選択します。たとえば、`.//egg`は、ツリー全体のすべての`egg`要素を選択します。
`..`	親要素を選択します。パスが開始要素の祖先に到達しようとした場合（要素`find`が呼び出された場合）、`None`を返します。
`[@attrib]`	指定された属性を持つすべての要素を選択します。
`[@attrib='value']`	指定された属性が指定された値を持つすべての要素を選択します。値に引用符を含めることはできません。
`[tag]`	`tag`という名前の子を持つすべての要素を選択します。直接の子のみがサポートされます。
`[.='text']`	子孫を含む完全なテキストコンテンツが指定された`text`に等しいすべての要素を選択します。バージョン3.7の新機能。
`[tag='text']`	`tag`という名前の子を持ち、子孫を含む完全なテキストコンテンツが指定された`text`と等しいすべての要素を選択します。
`[position]`	指定された位置にあるすべての要素を選択します。位置は、整数（1は最初の位置）、式`last()`（最後の位置の場合）、または最後の位置に相対的な位置（例： `last()-1`）。

述語（角括弧内の式）の前には、タグ名、アスタリスク、または別の述語を付ける必要があります。 position述部の前には、タグ名を付ける必要があります。

参照

関数

xml.etree.ElementTree.canonicalize(xml_data=None, *, out=None, from_file=None, **options)

C14N 2.0 変換関数。

正規化は、バイトごとの比較とデジタル署名を可能にする方法でXML出力を正規化する方法です。これにより、XMLシリアライザーの自由度が低下し、代わりに、より制約のあるXML表現が生成されます。主な制限は、名前空間宣言の配置、属性の順序、および無視できる空白に関するものです。

この関数は、XMLデータ文字列（ xml_data ）またはファイルパスまたはファイルのようなオブジェクト（ from_file ）を入力として受け取り、それを正規の形式に変換し、 out file（-like）オブジェクト（提供されている場合）、または提供されていない場合はテキスト文字列として返します。出力ファイルは、バイトではなくテキストを受け取ります。したがって、utf-8エンコーディングのテキストモードで開く必要があります。

典型的な使用法：

xml_data = "<root>...</root>"
print(canonicalize(xml_data))

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(xml_data, out=out_file)

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(from_file="inputfile.xml", out=out_file)

構成オプションは次のとおりです。

with_comments ：コメントを含めるにはtrueに設定します（デフォルト：false）
strip_text ：trueに設定すると、テキストコンテンツの前後の空白が削除されます

（デフォルト：false）
rewrite_prefixes ：trueに設定すると、名前空間プレフィックスが「n {number}」に置き換えられます。

（デフォルト：false）
qname_aware_tags ：プレフィックスが付いたqname対応タグ名のセット

テキストコンテンツで置き換える必要があります（デフォルト：空）
qname_aware_attrs ：接頭辞が付いたqname対応の属性名のセット

テキストコンテンツで置き換える必要があります（デフォルト：空）
exclude_attrs ：シリアル化してはならない属性名のセット
exclude_tags ：シリアル化してはならないタグ名のセット

上記のオプションリストで、「セット」とは、文字列のコレクションまたは反復可能オブジェクトを指し、順序付けは想定されていません。

バージョン3.8の新機能。

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

コメント要素ファクトリ。このファクトリ関数は、標準のシリアライザーによってXMLコメントとしてシリアル化される特別な要素を作成します。コメント文字列は、バイト文字列またはUnicode文字列のいずれかです。 text は、コメント文字列を含む文字列です。コメントを表す要素インスタンスを返します。

XMLParser は、コメントオブジェクトを作成する代わりに、入力内のコメントをスキップすることに注意してください。 ElementTree には、 Element メソッドのいずれかを使用してツリーに挿入されたコメントノードのみが含まれます。

xml.etree.ElementTree.dump(elem)

要素ツリーまたは要素構造をsys.stdoutに書き込みます。この関数は、デバッグにのみ使用する必要があります。

正確な出力形式は実装によって異なります。このバージョンでは、通常のXMLファイルとして記述されています。

elem は、要素ツリーまたは個々の要素です。

バージョン3.8で変更： dump（）関数は、ユーザーが指定した属性の順序を保持するようになりました。

xml.etree.ElementTree.fromstring(text, parser=None): 文字列定数からXMLセクションを解析します。 XML（）と同じです。 text は、XMLデータを含む文字列です。 parser は、オプションのパーサーインスタンスです。指定しない場合は、標準の XMLParser パーサーが使用されます。 Element インスタンスを返します。

xml.etree.ElementTree.fromstringlist(sequence, parser=None): 文字列フラグメントのシーケンスからXMLドキュメントを解析します。 sequence は、XMLデータフラグメントを含むリストまたはその他のシーケンスです。 parser は、オプションのパーサーインスタンスです。指定しない場合は、標準の XMLParser パーサーが使用されます。 Element インスタンスを返します。

バージョン3.2の新機能。

xml.etree.ElementTree.iselement(element): オブジェクトが有効な要素オブジェクトであるように見えるかどうかを確認してください。 element は要素インスタンスです。これが要素オブジェクトの場合は、Trueを返します。

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

XMLセクションを要素ツリーに段階的に解析し、何が起こっているかをユーザーに報告します。 source は、XMLデータを含むファイル名またはファイルオブジェクトです。 events は、報告する一連のイベントです。サポートされているイベントは、文字列"start"、"end"、"comment"、"pi"、"start-ns"、および"end-ns"（ ns」イベントは、詳細な名前空間情報を取得するために使用されます）。 events を省略すると、"end"イベントのみが報告されます。 parser は、オプションのパーサーインスタンスです。指定しない場合は、標準の XMLParser パーサーが使用されます。 parser は、 XMLParser のサブクラスである必要があり、デフォルトの TreeBuilder のみをターゲットとして使用できます。 (event, elem)ペアを提供するイテレータを返します。

iterparse（）はツリーを段階的に構築しますが、 source （または名前が付けられたファイル）でブロック読み取りを発行することに注意してください。そのため、読み取りをブロックできないアプリケーションには適していません。完全にノンブロッキングの解析については、 XMLPullParser を参照してください。

ノート

iterparse（）は、「開始」イベントを発行するときに開始タグの「>」文字が表示されることを保証するだけなので、属性は定義されていますが、テキスト属性とテール属性の内容は未定義です。その時点で。同じことが要素の子にも当てはまります。それらは存在する場合と存在しない場合があります。

完全に入力された要素が必要な場合は、代わりに「終了」イベントを探してください。

バージョン3.4以降非推奨： parser 引数。

バージョン3.8で変更： commentおよびpiイベントが追加されました。

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の内容を含む文字列です。処理命令を表す要素インスタンスを返します。

XMLParser は、コメントオブジェクトを作成する代わりに、入力の処理命令をスキップすることに注意してください。 ElementTree には、 Element メソッドの1つを使用してツリーに挿入された場合にのみ、処理命令ノードが含まれます。

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', *, xml_declaration=None, default_namespace=None, short_empty_elements=True): すべてのサブ要素を含むXML要素の文字列表現を生成します。 element は Element インスタンスです。 encoding 1 は出力エンコーディングです（デフォルトはUS-ASCIIです）。 encoding="unicode"を使用してUnicode文字列を生成します（そうでない場合は、バイト文字列が生成されます）。 メソッドは、"xml"、"html"、または"text"のいずれかです（デフォルトは"xml"）。 xml_declaration 、 default_namespace 、および short_empty_elements は、 ElementTree.write（）と同じ意味です。 XMLデータを含む（オプションで）エンコードされた文字列を返します。

バージョン3.4の新機能： short_empty_elements パラメーター。

バージョン3.8の新機能： xml_declaration および default_namespace パラメーター。

バージョン3.8で変更： tostring（）関数は、ユーザーが指定した属性の順序を保持するようになりました。

xml.etree.ElementTree.tostringlist(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True): すべてのサブ要素を含むXML要素の文字列表現を生成します。 element は Element インスタンスです。 encoding 1 は出力エンコーディングです（デフォルトはUS-ASCIIです）。 encoding="unicode"を使用してUnicode文字列を生成します（そうでない場合は、バイト文字列が生成されます）。 メソッドは、"xml"、"html"、または"text"のいずれかです（デフォルトは"xml"）。 xml_declaration 、 default_namespace 、および short_empty_elements は、 ElementTree.write（）と同じ意味です。 XMLデータを含む（オプションで）エンコードされた文字列のリストを返します。 b"".join(tostringlist(element)) == tostring(element)を除いて、特定のシーケンスを保証するものではありません。

バージョン3.2の新機能。

バージョン3.4の新機能： short_empty_elements パラメーター。

バージョン3.8の新機能： xml_declaration および default_namespace パラメーター。

バージョン3.8で変更： tostringlist（）関数は、ユーザーが指定した属性の順序を保持するようになりました。

xml.etree.ElementTree.XML(text, parser=None): 文字列定数からXMLセクションを解析します。この関数は、Pythonコードに「XMLリテラル」を埋め込むために使用できます。 text は、XMLデータを含む文字列です。 parser は、オプションのパーサーインスタンスです。指定しない場合は、標準の XMLParser パーサーが使用されます。 Element インスタンスを返します。

xml.etree.ElementTree.XMLID(text, parser=None): 文字列定数からXMLセクションを解析し、要素id：sから要素にマップする辞書も返します。 text は、XMLデータを含む文字列です。 parser は、オプションのパーサーインスタンスです。指定しない場合は、標準の XMLParser パーサーが使用されます。 Element インスタンスとディクショナリを含むタプルを返します。

XIncludeサポート

このモジュールは、xml.etree.ElementIncludeヘルパーモジュールを介して、 XIncludeディレクティブの限定的なサポートを提供します。このモジュールは、ツリー内の情報に基づいて、サブツリーとテキスト文字列を要素ツリーに挿入するために使用できます。

例

XIncludeモジュールの使用法を示す例を次に示します。現在のドキュメントにXMLドキュメントを含めるには、{http://www.w3.org/2001/XInclude}include要素を使用して、 parse 属性を"xml"に設定し、 href 属性を使用して含めるドキュメントを指定します。

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>

デフォルトでは、 href 属性はファイル名として扱われます。カスタムローダーを使用して、この動作をオーバーライドできます。また、標準ヘルパーはXPointer構文をサポートしていないことに注意してください。

このファイルを処理するには、通常どおりにファイルをロードし、ルート要素を xml.etree.ElementTree モジュールに渡します。

from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)

ElementIncludeモジュールは、{http://www.w3.org/2001/XInclude}include要素を source.xml ドキュメントのルート要素に置き換えます。結果は次のようになります。

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>This is a paragraph.</para>
</document>

parse 属性を省略すると、デフォルトで「xml」になります。 href属性は必須です。

テキストドキュメントを含めるには、{http://www.w3.org/2001/XInclude}include要素を使用し、 parse 属性を「text」に設定します。

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>

結果は次のようになります。

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) 2003.
</document>

参照

関数

xml.etree.ElementInclude.default_loader(href, parse, encoding=None): デフォルトのローダー。このデフォルトのローダーは、含まれているリソースをディスクから読み取ります。 href はURLです。 parse は、「xml」または「text」のいずれかの解析モード用です。 encoding は、オプションのテキストエンコーディングです。指定しない場合、エンコーディングはutf-8です。拡張されたリソースを返します。解析モードが"xml"の場合、これはElementTreeインスタンスです。解析モードが「テキスト」の場合、これはUnicode文字列です。ローダーが失敗した場合、Noneを返すか、例外を発生させる可能性があります。

xml.etree.ElementInclude.include(elem, loader=None): この関数は、XIncludeディレクティブを展開します。 elem はルート要素です。 ローダーはオプションのリソースローダーです。省略した場合、デフォルトで default_loader（）になります。指定する場合は、 default_loader（）と同じインターフェイスを実装する呼び出し可能オブジェクトである必要があります。拡張されたリソースを返します。解析モードが"xml"の場合、これはElementTreeインスタンスです。解析モードが「テキスト」の場合、これはUnicode文字列です。ローダーが失敗した場合、Noneを返すか、例外を発生させる可能性があります。

要素オブジェクト

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

要素クラス。このクラスはElementインターフェースを定義し、このインターフェースのリファレンス実装を提供します。

要素名、属性名、および属性値は、バイト文字列またはUnicode文字列のいずれかです。 tag は要素名です。 attrib は、要素属性を含むオプションの辞書です。 extra には、キーワード引数として指定された追加の属性が含まれています。

tag: この要素が表すデータの種類（つまり、要素タイプ）を識別する文字列。

text tail

これらの属性を使用して、要素に関連付けられた追加のデータを保持できます。それらの値は通常文字列ですが、アプリケーション固有のオブジェクトでもかまいません。要素がXMLファイルから作成されている場合、 text 属性は、要素の開始タグとその最初の子または終了タグの間のテキスト、またはNoneとテールのいずれかを保持します属性は、要素の終了タグと次のタグの間のテキスト、またはNoneのいずれかを保持します。 XMLデータの場合

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

a 要素には text 属性と tail 属性の両方にNoneがあり、 b 要素には text [ X125X] "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 を追加します。 サブエレメントがエレメントでない場合、 TypeError を発生させます。

extend(subelements): 0個以上の要素を持つシーケンスオブジェクトからサブ要素を追加します。サブ要素が要素でない場合、 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()

getiterator(tag=None)

insert(index, subelement): この要素の指定された位置にサブ要素を挿入します。 サブエレメントがエレメントでない場合、 TypeError を発生させます。

iter(tag=None): 現在の要素をルートとしてツリー iterator を作成します。イテレータは、この要素とその下のすべての要素をドキュメント（深さ優先）の順序で繰り返します。 tag がNoneまたは'*'でない場合、タグが tag と等しい要素のみがイテレーターから返されます。反復中にツリー構造が変更された場合、結果は未定義です。

バージョン3.2の新機能。

iterfind(match, namespaces=None): タグ名またはパスによって、一致するすべてのサブ要素を検索します。一致するすべての要素をドキュメント順に生成する反復可能オブジェクトを返します。 namespaces は、名前空間プレフィックスからフルネームへのオプションのマッピングです。

バージョン3.2の新機能。

itertext(): テキストイテレータを作成します。イテレータは、この要素とすべてのサブ要素をドキュメント順にループし、すべての内部テキストを返します。

バージョン3.2の新機能。

makeelement(tag, attrib): この要素と同じタイプの新しい要素オブジェクトを作成します。このメソッドを呼び出さないでください。代わりに SubElement（）ファクトリ関数を使用してください。

remove(subelement): 要素からサブ要素を削除します。 find *メソッドとは異なり、このメソッドは、タグ値やコンテンツではなく、インスタンスIDに基づいて要素を比較します。

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

Python 3.8より前は、要素のXML属性のシリアル化順序は、属性を名前で並べ替えることによって人為的に予測可能にされていました。現在保証されているdictの順序に基づいて、この任意の並べ替えはPython 3.8で削除され、属性がユーザーコードによって最初に解析または作成された順序が維持されました。

XML情報セットは情報の伝達から属性の順序を明示的に除外しているため、一般に、ユーザーコードは属性の特定の順序に依存しないようにする必要があります。入力時の順序を処理するためのコードを準備する必要があります。決定論的なXML出力が必要な場合、たとえば暗号署名またはテストデータセットの場合、正規のシリアル化は canonicalize（）関数で使用できます。

正規の出力が適用できないが、出力で特定の属性の順序が依然として望ましい場合、コードのリーダーの知覚の不一致を回避するために、コードは目的の順序で属性を直接作成することを目的とする必要があります。これを実現するのが難しい場合は、シリアル化の前に次のようなレシピを適用して、要素の作成とは独立して順序を適用できます。

def reorder_attributes(root):
    for el in root.iter():
        attrib = el.attrib
        if len(attrib) > 1:
            # adjust attribute order, e.g. by sorting
            attribs = sorted(attrib.items())
            attrib.clear()
            attrib.update(attribs)

ElementTreeオブジェクト

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

ElementTreeラッパークラス。このクラスは要素階層全体を表し、標準XMLとの間のシリアル化のサポートを追加します。

element はルート要素です。指定されている場合、ツリーは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)

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)

要素ツリーをXMLとしてファイルに書き込みます。 file はファイル名、または書き込み用に開かれたファイルオブジェクトです。 encoding 1 は出力エンコーディングです（デフォルトはUS-ASCIIです）。 xml_declaration は、XML宣言をファイルに追加する必要があるかどうかを制御します。 Falseを使用しない場合、Trueを常に使用する場合、Noneを使用するのは、US-ASCII、UTF-8、Unicode以外の場合のみです（デフォルトはNone）。 default_namespace は、デフォルトのXML名前空間（「xmlns」の場合）を設定します。 メソッドは、"xml"、"html"、または"text"のいずれかです（デフォルトは"xml"）。キーワードのみの short_empty_elements パラメーターは、コンテンツを含まない要素のフォーマットを制御します。 True（デフォルト）の場合、それらは単一の自己クローズタグとして発行されます。それ以外の場合は、開始/終了タグのペアとして発行されます。

出力は、文字列（ str ）またはバイナリ（ bytes ）のいずれかです。これは、 encoding 引数によって制御されます。 encoding が"unicode"の場合、出力は文字列です。それ以外の場合は、バイナリです。開いているファイルオブジェクトの場合、これはファイルのタイプと競合する可能性があることに注意してください。文字列をバイナリストリームに書き込もうとしないように注意してください。その逆も同様です。

バージョン3.4の新機能： short_empty_elements パラメーター。

バージョン3.8で変更： write（）メソッドは、ユーザーが指定した属性の順序を保持するようになりました。

これは、操作される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>

最初の段落のすべてのリンクの属性「ターゲット」を変更する例：

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

QNameオブジェクト

class xml.etree.ElementTree.QName(text_or_uri, tag=None): QNameラッパー。これは、出力で適切な名前空間処理を取得するために、QName属性値をラップするために使用できます。 text_or_uri は、{uri} localの形式のQName値を含む文字列です。タグ引数が指定されている場合は、QNameのURI部分です。 tag が指定されている場合、最初の引数はURIとして解釈され、この引数はローカル名として解釈されます。 QName インスタンスは不透明です。

TreeBuilderオブジェクト

class xml.etree.ElementTree.TreeBuilder(element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)

一般的な要素構造ビルダー。このビルダーは、start、data、end、comment、およびpiメソッド呼び出しのシーケンスを整形式の要素構造に変換します。このクラスを使用して、カスタムXMLパーサー、または他のXMLのような形式のパーサーを使用して要素構造を構築できます。

element_factory は、指定された場合、タグと属性のdictの2つの位置引数を受け入れる呼び出し可能である必要があります。新しい要素インスタンスを返すことが期待されています。

comment_factory および pi_factory 関数は、指定された場合、 Comment（）および ProcessingInstruction（）関数のように動作して、コメントと処理を作成する必要があります。手順。指定しない場合は、デフォルトのファクトリが使用されます。 insert_comments および/または insert_pis がtrueの場合、コメント/ pisは、ルート要素内に表示される場合（ただし、ツリー外には表示されない場合）にツリーに挿入されます。

close(): ビルダーバッファをフラッシュし、最上位のドキュメント要素を返します。 Element インスタンスを返します。

data(data): 現在の要素にテキストを追加します。 data は文字列です。これは、バイト文字列またはUnicode文字列のいずれかである必要があります。

end(tag): 現在の要素を閉じます。 tag は要素名です。閉じた要素を返します。

start(tag, attrs): 新しい要素を開きます。 tag は要素名です。 attrs は、要素属性を含む辞書です。開いた要素を返します。

comment(text): 指定されたテキストでコメントを作成します。 insert_commentsがtrueの場合、これもツリーに追加されます。

バージョン3.8の新機能。

pi(target, text): 指定されたターゲット名とテキストでコメントを作成します。 insert_pisがtrueの場合、これもツリーに追加されます。

バージョン3.8の新機能。

さらに、カスタム TreeBuilder オブジェクトは、次のメソッドを提供できます。

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

バージョン3.2の新機能。

start_ns(prefix, uri): パーサーが新しい名前空間宣言を検出するたびに、それを定義する開始要素のstart()コールバックの前に呼び出されます。 prefix は、デフォルトの名前空間ではであり、それ以外の場合は宣言された名前空間プレフィックス名です。 uri は名前空間URIです。

バージョン3.8の新機能。

end_ns(prefix): 名前空間プレフィックスマッピングを宣言した要素のend()コールバックの後に呼び出され、スコープ外になったプレフィックスの名前が付けられます。

バージョン3.8の新機能。

class xml.etree.ElementTree.C14NWriterTarget(write, *, with_comments=False, strip_text=False, rewrite_prefixes=False, qname_aware_tags=None, qname_aware_attrs=None, exclude_attrs=None, exclude_tags=None): C14N 2.0 ライター。引数は canonicalize（）関数の場合と同じです。このクラスはツリーを構築しませんが、 write 関数を使用して、コールバックイベントをシリアル化された形式に直接変換します。

バージョン3.8の新機能。

XMLParserオブジェクト

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

このクラスは、モジュールの低レベルの構成要素です。 xml.parsers.expat を使用して、XMLの効率的なイベントベースの解析を行います。 feed（）メソッドを使用してXMLデータを段階的にフィードでき、 target オブジェクトでコールバックを呼び出すことにより、解析イベントがプッシュAPIに変換されます。 target を省略すると、標準の TreeBuilder が使用されます。 encoding 1 が指定されている場合、値はXMLファイルで指定されているエンコーディングをオーバーライドします。

バージョン3.8で変更：パラメータがキーワードのみになりました。 html 引数はサポートされなくなりました。

close(): パーサーへのデータの供給を終了します。構築中に渡された target のclose()メソッドを呼び出した結果を返します。デフォルトでは、これは最上位のドキュメント要素です。

feed(data): データをパーサーにフィードします。 data はエンコードされたデータです。

XMLParser.feed（）は、開始タグごとに target ' s start(tag, attrs_dict)メソッド、終了タグごとにend(tag)メソッド、およびデータを呼び出します。メソッドdata(data)によって処理されます。さらにサポートされているコールバックメソッドについては、 TreeBuilder クラスを参照してください。 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

XMLPullParserオブジェクト

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

非ブロッキングアプリケーションに適したプルパーサー。その入力側APIは XMLParser のAPIと似ていますが、コールバックターゲットに呼び出しをプッシュする代わりに、 XMLPullParser は解析イベントの内部リストを収集し、ユーザーがそこから読み取れるようにします。 events は、報告する一連のイベントです。サポートされているイベントは、文字列"start"、"end"、"comment"、"pi"、"start-ns"、および"end-ns"（ ns」イベントは、詳細な名前空間情報を取得するために使用されます）。 events を省略すると、"end"イベントのみが報告されます。

feed(data): 指定されたバイトデータをパーサーにフィードします。

close(): データストリームが終了したことをパーサーに通知します。 XMLParser.close（）とは異なり、このメソッドは常に None を返します。パーサーが閉じられたときにまだ取得されていないイベントは、 read_events（）で読み取ることができます。

read_events()

パーサーに供給されたデータで発生したイベントのイテレーターを返します。イテレータは(event, elem)ペアを生成します。ここで、 event は、イベントのタイプを表す文字列です（例： "end"）および elem は、検出された Element オブジェクト、または次のような他のコンテキスト値です。

start、end：現在の要素。
comment、pi：現在のコメント/処理命令
start-ns：宣言された名前空間マッピングに名前を付けるタプル(prefix, uri)。
end-ns：なし（これは将来のバージョンで変更される可能性があります）

read_events（）の前回の呼び出しで提供されたイベントは、再度生成されません。イベントはイテレーターから取得された場合にのみ内部キューから消費されるため、 read_events（）から取得したイテレーターを並行して反復する複数のリーダーは予測できない結果になります。

ノート

XMLPullParser は、「開始」イベントを発行するときに開始タグの「>」文字が表示されることを保証するだけなので、属性は定義されますが、テキスト属性とテール属性の内容はその時点で未定義です。点。同じことが要素の子にも当てはまります。それらは存在する場合と存在しない場合があります。