"xml.etree.ElementTree" --- ElementTree XML API
***********************************************

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

======================================================================

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

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

バージョン 3.3 で非推奨: "xml.etree.cElementTree" モジュールは非推奨で
す。

警告:

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


チュートリアル
==============

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


XML 木構造と要素
----------------

XML は本質的に階層データ形式で、木構造で表すのが最も自然な方法です。
"ET" はこの目的のために 2 つのクラス - XML 文書全体を木で表す
"ElementTree" および木構造内の単一ノードを表す "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" に直接パースします。
"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 出力の生成時に含まれ
  ます。ドキュメントタイプ宣言は、 "XMLParser" コンストラクタにカスタ
  ムの "TreeBuilder" インスタンスを渡すことで、アクセスすることができ
  ます。


非ブロックパースのためのプル 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 ドキュメン
トを読んでいて、全てメモリ上にあるという状態にしたくない場合に有用です
。

Where *immediate* feedback through events is wanted, calling method
"XMLPullParser.flush()" can help reduce delay; please make sure to
study the related security notes.


関心ある要素の検索
------------------

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


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'):
   ...     # using root.findall() to avoid removal during traversal
   ...     rank = int(country.find('rank').text)
   ...     if rank > 50:
   ...         root.remove(country)
   ...
   >>> tree.write('output.xml')

Note that concurrent modification while iterating can lead to
problems, just like when iterating and modifying Python lists or
dicts. Therefore, the example first collects all matching elements
with "root.findall()", and only then iterates over the list of
matches.

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" の形式で修飾さ
れたタグと属性が、その *prefix* が完全な *URI* で置換された
"{uri}sometag" の形に展開されます。さらに、 デフォルトの XML 名前空間
があると、修飾されていない全てのタグにその完全 URI が前置されます。

ひとつは接頭辞 "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


XPath サポート
==============

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


使用例
------

以下はこのモジュールの 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]")

For XML with namespaces, use the usual qualified "{namespace}tag"
notation:

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


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

+-------------------------+--------------------------------------------------------+
| 操作                    | 意味                                                   |
|=========================|========================================================|
| "tag"                   | Selects all child elements with the given tag. For     |
|                         | example, "spam" selects all child elements named       |
|                         | "spam", and "spam/egg" selects all grandchildren named |
|                         | "egg" in all children named "spam". "{namespace}*"     |
|                         | selects all tags in the given namespace, "{*}spam"     |
|                         | selects tags named "spam" in any (or no) namespace,    |
|                         | and "{}*" only selects tags that are not in a          |
|                         | namespace.  バージョン 3.8 で変更: Support for star-   |
|                         | wildcards was added.                                   |
+-------------------------+--------------------------------------------------------+
| "*"                     | Selects all child elements, including comments and     |
|                         | processing instructions.  For example, "*/egg" selects |
|                         | all grandchildren named "egg".                         |
+-------------------------+--------------------------------------------------------+
| "."                     | 現在のノードを選択します。これはパスの先頭に置くことで |
|                         | 相対パスであるこ とを示すのに役立ちます。              |
+-------------------------+--------------------------------------------------------+
| "//"                    | 現在の要素の下にある全てのレベルの全ての子要素を選択し |
|                         | ます。例えば、 ".//egg" は木全体から "egg" 要素を選択  |
|                         | します。                                               |
+-------------------------+--------------------------------------------------------+
| ".."                    | 親ノードを選択します。パスが開始要素 ("find" が呼ばれ  |
|                         | た要素) の上の要 素に進もうとした場合 "None" を返しま  |
|                         | す。                                                   |
+-------------------------+--------------------------------------------------------+
| "[@attrib]"             | 与えられた属性を持つ全ての要素を選択します。           |
+-------------------------+--------------------------------------------------------+
| "[@attrib='value']"     | 与えられた属性が与えられた値を持つ全ての要素を選択しま |
|                         | す。 値に引用符 は含められません。                     |
+-------------------------+--------------------------------------------------------+
| "[@attrib!='value']"    | Selects all elements for which the given attribute     |
|                         | does not have the given value. The value cannot        |
|                         | contain quotes.  バージョン 3.10 で追加.               |
+-------------------------+--------------------------------------------------------+
| "[tag]"                 | "tag" という名前の子要素を持つ全ての要素を選択します。 |
|                         | 直下の子要素の みサポートしています。                  |
+-------------------------+--------------------------------------------------------+
| "[.='text']"            | 子孫のうち、与えられた "text" とテキスト全体が等しい全 |
|                         | ての要素を選択し ます。  バージョン 3.7 で追加.        |
+-------------------------+--------------------------------------------------------+
| "[.!='text']"           | Selects all elements whose complete text content,      |
|                         | including descendants, does not equal the given        |
|                         | "text".  バージョン 3.10 で追加.                       |
+-------------------------+--------------------------------------------------------+
| "[tag='text']"          | 子孫を含む完全なテキストコンテンツと与えられた "text"  |
|                         | が一致する、 "tag" と名付けられた子要素を持つすべての  |
|                         | 要素を選択します。                                     |
+-------------------------+--------------------------------------------------------+
| "[tag!='text']"         | Selects all elements that have a child named "tag"     |
|                         | whose complete text content, including descendants,    |
|                         | does not equal the given "text".  バージョン 3.10 で追 |
|                         | 加.                                                    |
+-------------------------+--------------------------------------------------------+
| "[position]"            | 与えられた位置にあるすべての要素を選択します。位置は整 |
|                         | 数 (先頭は 1)、 式 "last()" (末尾)、あるいは末尾からの |
|                         | 相対位置 (例えば "last()-1") の いずれかで指定できます |
|                         | 。                                                     |
+-------------------------+--------------------------------------------------------+

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


リファレンス
============


関数
----

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

   C14N 2.0 transformation function.

   Canonicalization is a way to normalise XML output in a way that
   allows byte-by-byte comparisons and digital signatures.  It reduced
   the freedom that XML serializers have and instead generates a more
   constrained XML representation.  The main restrictions regard the
   placement of namespace declarations, the ordering of attributes,
   and ignorable whitespace.

   This function takes an XML data string (*xml_data*) or a file path
   or file-like object (*from_file*) as input, converts it to the
   canonical form, and writes it out using the *out* file(-like)
   object, if provided, or returns it as a text string if not.  The
   output file receives text, not bytes.  It should therefore be
   opened in text mode with "utf-8" encoding.

   Typical uses:

      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)

   The configuration *options* are as follows:

   * *with_comments*: set to true to include comments (default: false)

   * *strip_text*: set to true to strip whitespace before and after
     text content
        (default: false)

   * *rewrite_prefixes*: set to true to replace namespace prefixes by
     "n{number}"
        (default: false)

   * *qname_aware_tags*: a set of qname aware tag names in which
     prefixes
        should be replaced in text content (default: empty)

   * *qname_aware_attrs*: a set of qname aware attribute names in
     which prefixes
        should be replaced in text content (default: empty)

   * *exclude_attrs*: a set of attribute names that should not be
     serialised

   * *exclude_tags*: a set of tag names that should not be serialised

   In the option list above, "a set" refers to any collection or
   iterable of strings, no ordering is expected.

   バージョン 3.8 で追加.

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

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

   "XMLParser" は、入力に含まれるコメントを読み飛ばし、コメントオブジ
   ェクトは作成しません。"ElementTree" は、"Element" メソッドの 1 つを
   使用して木内に挿入されたコメントノードのみを含みます。

xml.etree.ElementTree.dump(elem)

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

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

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

   バージョン 3.8 で変更: The "dump()" function now preserves the
   attribute order specified by the user.

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.indent(tree, space='  ', level=0)

   Appends whitespace to the subtree to indent the tree visually. This
   can be used to generate pretty-printed XML output. *tree* can be an
   Element or ElementTree.  *space* is the whitespace string that will
   be inserted for each indentation level, two space characters by
   default.  For indenting partial subtrees inside of an already
   indented tree, pass the initial indentation level as *level*.

   バージョン 3.9 で追加.

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()" は "start" イベントを発行した時に開始タグの文字 ">"
     が現れたことだけを保証します。そのため、属性は定義されますが、そ
     の時点ではテキストの内容も tail 属性も定義されていません。同じこ
     とは子要素にも言えて、その時点ではあるともないとも言えません。全
     部揃った要素が必要ならば、"end" イベントを探してください。

   バージョン 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 コンテンツを含む文字
   列にします。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)です。Unicode 文字列を生成する
   には、"encoding="unicode"" を使用してください。 *method* は
   ""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 で変更: The "tostring()" function now preserves the
   attribute order specified by the user.

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)です。Unicode 文字列を生成する
   には、"encoding="unicode"" を使用してください。 *method* は
   ""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 と要素を対応付ける
   辞書を返します。 *text* には XMLデータを含んだ文字列を指定します。
   *parser* はオプションで、パーザのインスタンスを指定します。指定され
   なかった場合、標準の "XMLParser" パーザを使用します。 "Element" の
   インスタンスと辞書のタプルを返します。


XInclude サポート
=================

This module provides limited support for XInclude directives, via the
"xml.etree.ElementInclude" helper module.  This module can be used to
insert subtrees and text strings into element trees, based on
information in the tree.


使用例
------

Here's an example that demonstrates use of the XInclude module. To
include an XML document in the current document, use the
"{http://www.w3.org/2001/XInclude}include" element and set the
**parse** attribute to ""xml"", and use the **href** attribute to
specify the document to include.

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

By default, the **href** attribute is treated as a file name. You can
use custom loaders to override this behaviour. Also note that the
standard helper does not support XPointer syntax.

To process this file, load it as usual, and pass the root element to
the "xml.etree.ElementTree" module:

   from xml.etree import ElementTree, ElementInclude

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

   ElementInclude.include(root)

The ElementInclude module replaces the
"{http://www.w3.org/2001/XInclude}include" element with the root
element from the **source.xml** document. The result might look
something like this:

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

If the **parse** attribute is omitted, it defaults to "xml". The href
attribute is required.

To include a text document, use the
"{http://www.w3.org/2001/XInclude}include" element, and set the
**parse** attribute to "text":

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

The result might look something like:

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


リファレンス
============


関数
----

xml.etree.ElementInclude.default_loader(href, parse, encoding=None)

   Default loader. This default loader reads an included resource from
   disk.  *href* is a URL. *parse* is for parse mode either "xml" or
   "text".  *encoding* is an optional text encoding.  If not given,
   encoding is "utf-8".  Returns the expanded resource.  If the parse
   mode is ""xml"", this is an ElementTree instance.  If the parse
   mode is "text", this is a Unicode string.  If the loader fails, it
   can return None or raise an exception.

xml.etree.ElementInclude.include(elem, loader=None, base_url=None, max_depth=6)

   This function expands XInclude directives.  *elem* is the root
   element.  *loader* is an optional resource loader.  If omitted, it
   defaults to "default_loader()". If given, it should be a callable
   that implements the same interface as "default_loader()".
   *base_url* is base URL of the original file, to resolve relative
   include file references.  *max_depth* is the maximum number of
   recursive inclusions.  Limited to reduce the risk of malicious
   content explosion. Pass a negative value to disable the limitation.

   Returns the expanded resource.  If the parse mode is ""xml"", this
   is an ElementTree instance.  If the parse mode is "text", this is a
   Unicode string.  If the loader fails, it can return None or raise
   an exception.

   バージョン 3.9 で追加: *base_url* と *max_depth* 引数。


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)

      Finds the first subelement matching *match*.  *match* may be a
      tag name or a path.  Returns an element instance or "None".
      *namespaces* is an optional mapping from namespace prefix to
      full name.  Pass "''" as prefix to move all unprefixed tag names
      in the expression into the given namespace.

   findall(match, namespaces=None)

      Finds all matching subelements, by tag name or path.  Returns a
      list containing all matching elements in document order.
      *namespaces* is an optional mapping from namespace prefix to
      full name.  Pass "''" as prefix to move all unprefixed tag names
      in the expression into the given namespace.

   findtext(match, default=None, namespaces=None)

      Finds text for the first subelement matching *match*.  *match*
      may be a tag name or a 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. *namespaces* is an optional mapping from
      namespace prefix to full name.  Pass "''" as prefix to move all
      unprefixed tag names in the expression into the given namespace.

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

   Prior to Python 3.8, the serialisation order of the XML attributes
   of elements was artificially made predictable by sorting the
   attributes by their name. Based on the now guaranteed ordering of
   dicts, this arbitrary reordering was removed in Python 3.8 to
   preserve the order in which attributes were originally parsed or
   created by user code.

   In general, user code should try not to depend on a specific
   ordering of attributes, given that the XML Information Set
   explicitly excludes the attribute order from conveying information.
   Code should be prepared to deal with any ordering on input. In
   cases where deterministic XML output is required, e.g. for
   cryptographic signing or test data sets, canonical serialisation is
   available with the "canonicalize()" function.

   In cases where canonical output is not applicable but a specific
   attribute order is still desirable on output, code should aim for
   creating the attributes directly in the desired order, to avoid
   perceptual mismatches for readers of the code. In cases where this
   is difficult to achieve, a recipe like the following can be applied
   prior to serialisation to enforce an order independently from the
   Element creation:

      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* は根要素です。*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()" と同じで、木の根要素を起点とします。

   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" 用) を指定します。 *method*
      は ""xml"", ""html"", ""text"" のいずれかです (デフォルトは
      ""xml"" です)。 キーワード専用の *short_empty_elements* 引数は、
      内容がない属性のフォーマットを制御します。 "True" (既定) の場合
      、単一の空要素タグとして書かれ、"False" の場合、開始タグと終了タ
      グのペアとしてかかれます。

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

      バージョン 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>

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


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" インスタンスは不透明です。


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*, when given, must be a callable accepting two
   positional arguments: a tag and a dict of attributes.  It is
   expected to return a new element instance.

   The *comment_factory* and *pi_factory* functions, when given,
   should behave like the "Comment()" and "ProcessingInstruction()"
   functions to create comments and processing instructions.  When not
   given, the default factories will be used.  When *insert_comments*
   and/or *insert_pis* is true, comments/pis will be inserted into the
   tree if they appear within the root element (but not outside of
   it).

   close()

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

   data(data)

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

   end(tag)

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

   start(tag, attrs)

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

   comment(text)

      Creates a comment with the given *text*.  If "insert_comments"
      is true, this will also add it to the tree.

      バージョン 3.8 で追加.

   pi(target, text)

      Creates a comment with the given *target* name and *text*.  If
      "insert_pis" is true, this will also add it to the tree.

      バージョン 3.8 で追加.

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

   doctype(name, pubid, system)

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

      バージョン 3.2 で追加.

   start_ns(prefix, uri)

      Is called whenever the parser encounters a new namespace
      declaration, before the "start()" callback for the opening
      element that defines it. *prefix* is "''" for the default
      namespace and the declared namespace prefix name otherwise.
      *uri* is the namespace URI.

      バージョン 3.8 で追加.

   end_ns(prefix)

      Is called after the "end()" callback of an element that declared
      a namespace prefix mapping, with the name of the *prefix* that
      went out of scope.

      バージョン 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)

   A C14N 2.0 writer.  Arguments are the same as for the
   "canonicalize()" function.  This class does not build a tree but
   translates the callback events directly into a serialised form
   using the *write* function.

   バージョン 3.8 で追加.


XMLParser オブジェクト
----------------------

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

   このクラスは、このモジュールの構成要素のうち、低水準のものです。効
   率的でイベントベースのXMLパースのため、"xml.parsers.expat" を使用し
   ます。"feed()" メソッドで XML データをインクリメンタルに受け取り、
   *target* オブジェクトのコールバックを呼び出すことで、パースイベント
   をプッシュ API に変換します。*target* が省略された場合、標準の
   "TreeBuilder" が使用されます。 *encoding* [1] が指定された場合、こ
   のあたいは XML ファイル内で指定されたエンコーディングを上書きします
   。

   バージョン 3.8 で変更: Parameters are now keyword-only. The *html*
   argument no longer supported.

   close()

      パーザへのデータの提供を完了します。構築中に渡される *target* の
      "close()" メソッドを呼び出す結果を返します。既定では、これがトッ
      プレベルのドキュメント要素になります。

   feed(data)

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

   flush()

      Triggers parsing of any previously fed unparsed data, which can
      be used to ensure more immediate feedback, in particular with
      Expat >=2.6.0. The implementation of "flush()" temporarily
      disables reparse deferral with Expat (if currently enabled) and
      triggers a reparse. Disabling reparse deferral has security
      consequences; please see
      "xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()" for
      details.

      Note that "flush()" has been backported to some prior releases
      of CPython as a security fix.  Check for availability of
      "flush()" using "hasattr()" if used in code running across a
      variety of Python versions.

      バージョン 3.10.14 で追加.

   "XMLParser.feed()" は *target* の "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" のものと似ていますが、コールバックターゲットに呼び出し
   をプッシュするのではなく、 "XMLPullParser" はパースイベントの内部リ
   ストを収集し、ユーザーがそこから読み出すことができます。*events* は
   、呼び出し元に報告するイベントのシーケンスです。サポートされている
   イベントは、文字列の ""start"", ""end"", ""comment"", ""pi"",
   ""start-ns"", ""end-ns"" ("ns" イベントは、名前空間の詳細情報の取得
   に使用) です。*events* が省略された場合、 ""end"" イベントのみが報
   告されます。

   feed(data)

      指定したバイトデータをパーザに与えます。

   flush()

      Triggers parsing of any previously fed unparsed data, which can
      be used to ensure more immediate feedback, in particular with
      Expat >=2.6.0. The implementation of "flush()" temporarily
      disables reparse deferral with Expat (if currently enabled) and
      triggers a reparse. Disabling reparse deferral has security
      consequences; please see
      "xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()" for
      details.

      Note that "flush()" has been backported to some prior releases
      of CPython as a security fix.  Check for availability of
      "flush()" using "hasattr()" if used in code running across a
      variety of Python versions.

      バージョン 3.10.14 で追加.

   close()

      パーザに、データストリームが終了したことを伝えます。
      "XMLParser.close()" とは異なり、このメソッドは常に "None" を返し
      ます。パーザがクローズした時にまだ帰って来ていないイベントは、ま
      だ "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, or other context value as follows.

      * "start", "end": the current Element.

      * "comment", "pi": the current comment / processing instruction

      * "start-ns": a tuple "(prefix, uri)" naming the declared
        namespace mapping.

      * "end-ns": "None" (this may change in a future version)

      "read_events()" の前の呼び出しで提供されたイベントは、再度 yield
      されることはありません。イベントは、イテレータから取得された場合
      にのみ内部キューから消費されるため、"read_events()" から取得され
      たイテレータに対して複数の読み出しを並行して反復的に行うと、予期
      せぬ結果が引き起こされます。

   注釈:

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

   バージョン 3.4 で追加.

   バージョン 3.8 で変更: イベント "comment", "pi" が追加されました。


例外
----

class xml.etree.ElementTree.ParseError

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

   code

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

   position

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

-[ 脚注 ]-

[1] 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 を参照してください。
