\section{\module{xml.etree.ElementTree} --- ElementTree XML API}
\declaremodule{standard}{xml.etree.ElementTree}
\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
\modulesynopsis{Implementation of the ElementTree API.}

\versionadded{2.5}

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

各エレメントは関連する多くのプロパティを具えています:

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

エレメントのインスタンスを作るには、Element や SubElement といったファクトリー
関数を使います。

\class{ElementTree} クラスはエレメントの構造を包み込み、それと XML を行き来す
るのに使えます。

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


\subsection{関数\label{elementtree-functions}}

\begin{funcdesc}{Comment}{\optional{text}}
コメント・エレメントのファクトリーです。このファクトリー関数は XML コメントにシリアライズ
される特別な要素を作ります。
コメント文字列は、8-bit ASCII 文字列でも Unicode 文字列でも構いません。
\var{text} はそのコメント文字列を含んだ文字列です。

\begin{datadescni}{戻り値:}
コメントを表わすエレメントのインスタンス。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{dump}{elem}
エレメントの木もしくはエレメントの構造を sys.stdout に書き込みます。この関数は
デバグ目的でだけ使用してください。

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

\var{elem} はエレメントの木もしくは個別のエレメントです。
\end{funcdesc}

\begin{funcdesc}{Element}{tag\optional{, attrib}\optional{, **extra}}
エレメントのファクトリー。この関数は標準エレメント・インタフェースを実装した
オブジェクトを返します。このオブジェクトのクラスや型が正確に何であるかは
実装に依存しますが、いつでもこのモジュールにある {\_}ElementInterface クラスと
互換性があります。

エレメント名、アトリビュート名およびアトリビュート値は8-bit ASCII 文字列でも
Unicode 文字列でも構いません。
\var{tag} はエレメント名です。
\var{attrib} はオプションの辞書で、エレメントのアトリビュートを含んでいます。
\var{extra} は追加のアトリビュートで、キーワード引数として与えられたものです。

\begin{datadescni}{戻り値:}
エレメント・インスタンス。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{fromstring}{text}
文字列定数で与えられた XML 断片を構文解析します。XML 関数と同じです。
\var{text} は XML データを含んだ文字列です。

\begin{datadescni}{戻り値:}
エレメント・インスタンス。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{iselement}{element}
オブジェクトが正当なエレメント・オブジェクトであるかをチェックします。
\var{element} はエレメント・インスタンスです。

\begin{datadescni}{戻り値:}
引数がエレメント・オブジェクトならば真値。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{iterparse}{source\optional{, events}}
XML 断片を構文解析してエレメントの木を漸増的に作っていき、その間
進行状況をユーザーに報告します。
\var{source} は XML データを含むファイル名またはファイル風オブジェクト。
\var{events} は報告すべきイベントのリスト。省略された場合は ``end''
イベントだけが報告されます。

\begin{datadescni}{戻り値:}
(イベント, エレメント) イテレータ。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{parse}{source\optional{, parser}}
XML 断片を構文解析してエレメントの木にしていきます。
\var{source} は XML データを含むファイル名またはファイル風オブジェクト。
\var{parser} はオプションの構文解析器インスタンスです。これが与えられない場合、
標準の XMLTreeBuilder 構文解析器が使われます。

\begin{datadescni}{戻り値:}
ElementTree インスタンス。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{ProcessingInstruction}{target\optional{, text}}
PI エレメントのファクトリー。このファクトリー関数は XML の
処理命令(processing instruction)
としてシリアライズされる特別なエレメントを作ります。
\var{target} は PI ターゲットを含んだ文字列です。
\var{text} は与えられるならば PI コンテンツを含んだ文字列です。

\begin{datadescni}{戻り値:}
PI を表わすエレメント・インスタンス。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{SubElement}{parent, tag\optional{, attrib} \optional{, **extra}}
部分エレメントのファクトリー。この関数はエレメント・インスタンスを作り、それを
既存のエレメントに追加します。

エレメント名、アトリビュート名およびアトリビュート値は8-bit ASCII 文字列でも
Unicode 文字列でも構いません。
\var{parent} は親エレメントです。
\var{tag} はエレメント名です。
\var{attrib} はオプションの辞書で、エレメントのアトリビュートを含んでいます。
\var{extra} は追加のアトリビュートで、キーワード引数として与えられたものです。

\begin{datadescni}{戻り値:}
エレメント・インスタンス。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{tostring}{element\optional{, encoding}}
XML エレメントを全ての子エレメントを含めて表現する文字列を生成します。
\var{element} はエレメント・インスタンス。
\var{encoding} は出力エンコーディング(デフォルトは US-ASCII)です。

\begin{datadescni}{戻り値:}
XML データを含んだエンコードされた文字列。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{XML}{text}
文字列定数で与えられた XML 断片を構文解析します。この関数は Python コードに
「XML リテラル」を埋め込むのに使えます。
\var{text} は XML データを含んだ文字列です。

\begin{datadescni}{戻り値:}
エレメント・インスタンス。
\end{datadescni}
\end{funcdesc}

\begin{funcdesc}{XMLID}{text}
文字列定数で与えられた XML 断片を構文解析し、エレメント ID からエレメント
へのマッピングを与える辞書も同時に返します。
\var{text} は XML データを含んだ文字列です。

\begin{datadescni}{戻り値:}
エレメント・インスタンスと辞書のタプル。
\end{datadescni}
\end{funcdesc}


\subsection{ElementTree オブジェクト\label{elementtree-elementtree-objects}}

\begin{classdesc}{ElementTree}{\optional{element,} \optional{file}}
ElementTree ラッパー・クラス。このクラスはエレメントの全階層を表現し、
さらに標準 XML との相互変換を追加しています。

\var{element} は根エレメントです。
木はもし \var{file} が与えられればその XML の内容により初期化されます。
\end{classdesc}

\begin{methoddesc}{_setroot}{element}
この木の根エレメントを置き換えます。したがって現在の木の内容は破棄され、
与えられたエレメントが代わりに使われます。注意して使ってください。
\var{element} はエレメント・インスタンスです。
\end{methoddesc}

\begin{methoddesc}{find}{path}
子孫エレメントの中で与えられたタグを持つ最初のものを見つけます。
getroot().find(path) と同じです。
\var{path} は探したいエレメントです。

\begin{datadescni}{戻り値:}
最初に条件に合ったエレメント、または見つからない時は None。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{findall}{path}
子孫エレメントの中で与えられたタグを持つものを全て見つけます。
getroot().findall(path) と同じです。
\var{path} は探したいエレメントです。

\begin{datadescni}{戻り値:}
全ての条件に合ったエレメントのリストまたはイテレータで、セクション順です。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{findtext}{path\optional{, default}}
子孫エレメントの中で与えられたタグを持つ最初のもののテキストを見つけます。
getroot().findtext(path) と同じです。
\var{path} は探したい直接の子エレメントです。
\var{default} はエレメントが見つからなかった場合に返される値です。

\begin{datadescni}{戻り値:}
条件に合った最初のエレメントのテキスト、または見つからなかった場合にはデフォルト値。
もしエレメントが見つかったもののテキストがなかった場合には、このメソッドは空文字列を返す、
ということに気をつけてください。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{getiterator}{\optional{tag}}
根エレメントに対する木を巡るイテレータを作ります。イテレータは木の全てのエレメントに
渡ってセクション順にループします。
\var{tag} は探したいタグです(デフォルトでは全てのエレメントを返します)。

\begin{datadescni}{戻り値:}
イテレータ。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{getroot}{}
この木の根エレメントを返します。

\begin{datadescni}{戻り値:}
エレメント・インスタンス。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{parse}{source\optional{, parser}}
外部の XML 断片をこのエレメントの木に読み込みます。
\var{source} は XML データを含むファイル名またはファイル風オブジェクト。
\var{parser} はオプションの構文解析器インスタンスです。これが与えられない場合、
標準の XMLTreeBuilder 構文解析器が使われます。

\begin{datadescni}{戻り値:}
断片の根エレメント。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{write}{file\optional{, encoding}}
エレメントの木をファイルに XML として書き込みます。
\var{file} はファイル名またはファイル風オブジェクトで書き込み用に開かれたもの。
\var{encoding} は出力エンコーディング(デフォルトは US-ASCII)です。
\end{methoddesc}


\subsection{QName オブジェクト\label{elementtree-qname-objects}}

\begin{classdesc}{QName}{text_or_uri\optional{, tag}}
QName ラッパー。このクラスは QName アトリビュート値をラップし、出力時に
真っ当な名前空間の扱いを得るために使われます。
\var{text_or_uri} は {\{}uri{\}}local という形式の QName 値を含む文字列、
または tag 引数が与えられた場合には QName の URI 部分の文字列です。
\var{tag} が与えられた場合、一つめの引数は URI と解釈され、この引数は
ローカル名と解釈されます。

\begin{datadescni}{戻り値:}
QName を表わす不透明オブジェクト。
\end{datadescni}
\end{classdesc}


\subsection{TreeBuilder オブジェクト\label{elementtree-treebuilder-objects}}

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

\begin{methoddesc}{close}{}
構文解析器のバッファをフラッシュし、最上位の文書エレメントを返します。

\begin{datadescni}{戻り値:}
エレメント・インスタンス。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{data}{data}
現在のエレメントにテキストを追加します。
\var{data} は文字列です。8-bit ASCII 文字列もしくは
Unicode 文字列でなければなりません。
\end{methoddesc}

\begin{methoddesc}{end}{tag}
現在のエレメントを閉じます。
\var{tag} はエレメントの名前です。

\begin{datadescni}{戻り値:}
閉じられたエレメント。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{start}{tag, attrs}
新しいエレメントを開きます。
\var{tag} はエレメントの名前です。
\var{attrs} はエレメントのアトリビュートを保持した辞書です。

\begin{datadescni}{戻り値:}
開かれたエレメント。
\end{datadescni}
\end{methoddesc}


\subsection{XMLTreeBuilder オブジェクト\label{elementtree-xmltreebuilder-objects}}

\begin{classdesc}{XMLTreeBuilder}{\optional{html,} \optional{target}}
XML ソースからエレメント構造を作るもので、expat 構文解析器に基づいています。
\var{html} は前もって定義された HTML エンティティです。このオプションは
現在の実装ではサポートされていません。
\var{target} はターゲットとなるオブジェクトです。省略された場合、標準の
TreeBuilder クラスのインスタンスが使われます。
\end{classdesc}

\begin{methoddesc}{close}{}
構文解析器にデータを供給するのを終わりにします。

\begin{datadescni}{戻り値:}
エレメント構造。
\end{datadescni}
\end{methoddesc}

\begin{methoddesc}{doctype}{name, pubid, system}
doctype 宣言を扱います。
\var{name} は doctype の名前です。
\var{pubid} は公開識別子です。
\var{system} はシステム識別子です。
\end{methoddesc}

\begin{methoddesc}{feed}{data}
構文解析器にデータを供給します。

\var{data} はエンコードされたデータです。
\end{methoddesc}
