バージョン 2.5 で追加.
Element 型は柔軟性のあるコンテナオブジェクトで、階層的データ構造をメモリーに格納するようにデザインされています。この型は言わばリストと辞書の間の子のようなものです。
各エレメントは関連する多くのプロパティを具えています:
element のインスタンスを作るには、 Element コンストラクタや SubElement() ファクトリー関数を使います。
ElementTree クラスはエレメントの構造を包み込み、それと XML を行き来するのに使えます。
この API の C 実装である xml.etree.cElementTree も使用可能です。
チュートリアルその他のドキュメントへのリンクについては http://effbot.org/zone/element-index.htm を参照して下さい。 Fredrik Lundh のページも xml.etree.ElementTree の開発バージョンの置き場所です。
バージョン 2.7 で変更: ElementTree API が 1.3 に更新されました。 より詳しい情報については、 Introducing ElementTree 1.3 を参照してください。
コメント・エレメントのファクトリーです。このファクトリー関数は、標準のシリアライザでは XML コメントにシリアライズされる特別な要素を作ります。コメント文字列は byte 文字列でも Unicode 文字列でも構いません。 text はそのコメント文字列を含んだ文字列です。コメントを表わすエレメントのインスタンスを返します。
エレメントの木もしくはエレメントの構造を sys.stdout に書き込みます。この関数はデバグ目的でだけ使用してください。
出力される形式の正確なところは実装依存です。このバージョンでは、通常の XML ファイルとして書き込まれます。
elem はエレメントの木もしくは個別のエレメントです。
文字列定数で与えられた XML 断片を構文解析します。 XML() 関数と同じです。 text は XML データの文字列です。 Element インスタンスを返します。
文字列のシーケンスからXMLドキュメントを解析します。 sequence は XML データのフラグメントを格納した、 list かその他のシーケンスです。 parser はオプションの parser インスタンスです。指定されなかった場合、標準の XMLParser パーサーが利用されます。 Elment インスタンスを返します。
バージョン 2.7 で追加.
オブジェクトが正当なエレメント・オブジェクトであるかをチェックします。 element はエレメント・インスタンスです。引数がエレメント・オブジェクトならば真値を返します。
XML 断片を構文解析してエレメントの木を漸増的に作っていき、その間進行状況をユーザーに報告します。 source は XML データを含むファイル名またはファイル風オブジェクト。 events は報告すべきイベントのリスト。省略された場合は “end” イベントだけが報告されます。 parser はオプションの引数で、パーサーのインスタンスを指定します。指定されなかった場合は標準の XMLParser が利用されます。 (event, elem) ペアのイテレータ(iterator)を返します。
ノート
iterparse() は “start” イベントを送り出すとき開始タグの “>” なる文字を見たことだけを保証しますので、アトリビュートは定義されますが、その時点ではテキストの内容もテール・アトリビュートもまだ定義されていません。同じことは子エレメントにも言えて、その時点ではあるともないとも言えません。
全部が揃ったエレメントが必要ならば、”end” イベントを探すようにして下さい。
XML 断片を構文解析して element tree にします。 source は XML データを含むファイル名またはファイル風オブジェクト。 parser はオプションの構文解析器インスタンスです。これが与えられない場合、標準の XMLParser パーサーが使われます。 ElementTree インスタンスを返します。
PI エレメントのファクトリー。このファクトリー関数は XML の処理命令(processing instruction) としてシリアライズされる特別なエレメントを作ります。 target は PI ターゲットを含んだ文字列です。 text は与えられるならば PI コンテンツを含んだ文字列です。 PI を表わすエレメント・インスタンスを返します。
名前空間の prefix を登録します。レジストリはグローバルで、与えられた prefix か名前空間URI のどちらかの既存のマッピングは全て削除されます。 prefix は名前空間の prefix です。 uri は名前空間のURIです。この名前空間のタグや属性は、可能な限り与えられた prefix をつけてシリアライズされます。
バージョン 2.7 で追加.
子エレメントのファクトリー。この関数はエレメント・インスタンスを作り、それを既存のエレメントに追加します。
エレメント名、アトリビュート名およびアトリビュート値は byte 文字列でも Unicode 文字列でも構いません。 parent は親エレメントです。 tag はエレメント名です。 attrib はオプションの辞書で、エレメントのアトリビュートを含んでいます。 extra は追加のアトリビュートで、キーワード引数として与えられたものです。エレメント・インスタンスを返します。
XML エレメントを全ての子エレメントを含めて表現する文字列を生成します。 element は Element のインスタンスです。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。 method は "xml", "html", "text" のいずれか(デフォルトは "xml") です。 XML データを含んだエンコードされた文字列を返します。
XML エレメントを全ての子エレメントを含めて表現する文字列を生成します。 element は Element のインスタンスです。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。 method は "xml", "html", "text" のいずれか(デフォルトは "xml") です。 XML データを含んだエンコードされた文字列のリストを返します。これは、 "".join(tostringlist(element)) == tostring(element) であること以外、なにか特定のシーケンスになることは保証していません。
バージョン 2.7 で追加.
エレメントクラス。この関数は Element インタフェースを定義すると同時に、そのリファレンス実装を提供します。
エレメント名、アトリビュート名およびアトリビュート値は bytes 文字列でも Unicode 文字列でも構いません。 tag はエレメント名です。 attrib はオプションの辞書で、エレメントのアトリビュートを含んでいます。 extra は追加のアトリビュートで、キーワード引数として与えられたものです。エレメント・インスタンスを返します。
このエレメントが表すデータの種類を示す文字列です(言い替えると、エレメントの型です)。
text アトリビュートはエレメントに結びつけられた付加的なデータを保持するのに使われます。名前が示唆しているようにこのアトリビュートはたいてい文字列ですが、アプリケーション固有のオブジェクトであって構いません。エレメントが XML ファイルから作られたものならば、このアトリビュートはエレメント・タグの間にあるテキストを丸ごと含みます。
tail アトリビュートはエレメントに結びつけられた付加的なデータを保持するのに使われます。このアトリビュートはたいてい文字列ですが、アプリケーション固有のオブジェクトであって構いません。エレメントが XML ファイルから作られたものならば、このアトリビュートはエレメントの終了タグと次のタグの直前までの間に見つかったテキストを丸ごと含みます。
エレメントのアトリビュートを保持する辞書です。次のことに注意しましょう。 attrib は普通の書き換え可能な Python の辞書ではあるのですが、 ElementTree の実装によっては別の内部表現を選択して要求されたときにだけ辞書を作るようにするかもしれません。そうした実装の利益を享受するために、可能な限り下記の辞書メソッドを通じて使いましょう。
以下の辞書風メソッドがエレメントのアトリビュートに対して働きます。
エレメントをリセットします。全ての子孫エレメントを削除し、アトリビュートをクリアし、 test と tail を None にセットします。
エレメントの key という名前のアトリビュートを取得します。
アトリビュートの値、またはアトリビュートがない場合は default を返します。
エレメントのアトリビュートを (名前, 値) ペアのシーケンスとして返します。返されるアトリビュートの順番は決まっていません。
エレメントのアトリビュート名をリストとして返します。返される名前の順番は決まっていません。
エレメントのアトリビュート key に value をセットします。
以下のメソッドはエレメントの子(サブエレメント)に対して働きます。
エレメント subelement をこのエレメントの内部にあるサブエレメントのリストの最後に追加します。
シーケンスオブジェクト subelements から 0個以上のサブエレメントを追加します。サブエレメントが有効なオブジェクトでない場合は AssertionError を発生させます。
バージョン 2.7 で追加.
match にマッチする最初のサブエレメントを探します。 match はタグ名かパス(path)です。エレメント・インスタンスまたは None を返します。
タグ名かパスにマッチする全てのサブエレメントを探します。全てのマッチするエレメントを、ドキュメント上の順序で含むリストを返します。
match にマッチする最初のサブエレメントのテキストを探します。 match はタグ名かパスです。最初にマッチするエレメントの text を返すか、エレメントが見あたらなかった場合 default を返します。マッチしたエレメントに text がなければ空文字列が返されるので気を付けましょう。
バージョン 2.7 で撤廃: list(elem) を使うか、 Element に対してイテレートしてください。
バージョン 2.7 で撤廃: Element.iter() メソッドを使ってください。
サブエレメントをこのエレメントの与えられた位置に挿入します。
現在のエレメントを根とするツリーのイテレータ(iterator)を作ります。イテレータは現在のエレメントとそれ以下の全てのエレメントを、文書中での出現順(深さ優先順)でイテレートします。 tag が None または '*' でない場合は、与えられたタグに等しいものについてのみイテレータから返されます。イテレート中にツリー構造が変更された場合の結果は未定義です。
タグ名かパスにマッチする全てのサブエレメントを探します。全てのマッチするエレメントをドキュメント上の順序で yield するイテレート可能オブジェクトを返します。
バージョン 2.7 で追加.
text のイテレータを作成します。このイテレータは、このエレメントと全てのサブエレメントをドキュメント上の順序で巡回し、全ての内部の text を返します。
バージョン 2.7 で追加.
現在のエレメントと同じ型の新しいエレメント・オブジェクトを作ります。このメソッドは呼び出さずに、 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"
ElementTree ラッパー・クラス。このクラスはエレメントの全階層を表現し、さらに標準 XML との相互変換を追加しています。
element は根エレメントです。木はもし file が与えられればその XML の内容により初期化されます。
この木の根エレメントを置き換えます。したがって現在の木の内容は破棄され、与えられたエレメントが代わりに使われます。注意して使ってください。 element はエレメント・インスタンスです。
match にマッチする最初のトップレベルのエレメントを探します。 match はタグ名かパスです。 getroot().find(path) と同じです。最初に条件に合ったエレメント、または見つからない時は None を返します。
タグ名かパスにマッチする全てのサブエレメントを探します。 getroot().findall(match) と同じです。 match はタグ名かパスです。条件に合った全てのエレメントを、ドキュメント上の順序で格納したリストを返します。
子孫エレメントの中で与えられたタグを持つ最初のもののテキストを見つけます。 getroot().findtext(match) と同じです。 match はタグ名かパスです。 default はエレメントが見つからなかった場合に返される値です。条件に合った最初のエレメントのテキスト、または見つからなかった場合にはデフォルト値を返します。もしエレメントが見つかったもののテキストがなかった場合には、このメソッドは空文字列を返すということに気をつけてください。
バージョン 2.7 で撤廃: 代わりに ElementTree.iter() メソッドを利用してください。
この木の根エレメントを返します。
ルートエレメントに対する、ツリーを巡回するイテレータを返します。イテレータはツリーの全てのエレメントに渡ってセクション順にループします。 tag は探したいタグです(デフォルトでは全てのエレメントを返します)。
タグ名かパスにマッチする全てのサブエレメントを返します。 getroot().iterfind(match) と同じです。全てのマッチするエレメントをドキュメント順に yield するイテレート可能オブジェクトを返します。
バージョン 2.7 で追加.
外部の XML 断片をこのエレメントの木に読み込みます。 source は XML データを含むファイル名またはファイル風オブジェクト。 parser はオプションの構文解析器インスタンスです。これが与えられない場合、標準の XMLParser パーサーが使われます。断片の根エレメントを返します。
エレメントの木をファイルに XML として書き込みます。 file はファイル名またはファイル風オブジェクトで書き込み用に開かれたもの。 encoding [1] は出力エンコーディング(デフォルトは US-ASCII)です。 xml_declaration は、 XML 宣言がファイルに書かれるかどうかを制御します。 False の場合は常に書かれず、 True の場合は常に書かれ、 None の場合は US-ASCII か UTF-8 以外の場合に書かれます (デフォルトは None です)。 method は "xml", "html", "text" のいづれかです (デフォルトは "xml" です)。エンコードされた文字列を返します。
次に示すのがこれから操作する XML ファイルです:
<html>
<head>
<title>Example page</title>
</head>
<body>
<p>Moved to <a href="http://example.org/">example.org</a>
or <a href="http://example.com/">example.com</a>.</p>
</body>
</html>
第1段落の全てのリンクの “target” アトリビュートを変更する例:
>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p") # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a")) # Returns list of all links
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links: # Iterates through all found links
... i.attrib["target"] = "blank"
>>> tree.write("output.xhtml")
汎用のエレメント構造ビルダー。これは start, data, end のメソッド呼び出しの列を整形式のエレメント構造に変換します。このクラスを使うと、好みの XML 構文解析器、または他の XML に似た形式の構文解析器を使って、エレメント構造を作り出すことができます。 element_factory が与えられた場合には、新しい Element インスタンスを作る際にこれを呼び出します。
現在のエレメントにテキストを追加します。 data は文字列です。 bytes 文字列もしくは Unicode 文字列でなければなりません。
現在のエレメントを閉じます。 tag はエレメントの名前です。閉じられたエレメントを返します。
新しいエレメントを開きます。 tag はエレメントの名前です。 attrs はエレメントのアトリビュートを保持した辞書です。開かれたエレメントを返します。
加えて、カスタムの TreeBuilder オブジェクトは以下のメソッドを提供できます。
doctype 宣言を処理します。 name は doctype 名です。 pubid は公式の識別子です。 system はシステム識別子です。このメソッドはデフォルトの TreeBuilder クラスには存在しません。
バージョン 2.7 で追加.
XML ソースからエレメント構造を作るもので、expat 構文解析器に基づいています。 html は前もって定義された HTML エンティティです。このオプションは現在の実装ではサポートされていません。 target はターゲットとなるオブジェクトです。省略された場合、標準の TreeBuilder クラスのインスタンスが使われます。
expat パーサーを利用した、XML ソースデータからの Element 構造ビルダー。 html は定義済みの HTML エンティティです。このフラグは現在の実装ではサポートされていません。 target はターゲットオブジェクトです。省略された場合、ビルダーは標準の TreeBuilder クラスのインスタンスを利用します。 encoding [1] はオプションで、与えられた場合は XML ファイルで指定されたエンコーディングをオーバーライドします。
構文解析器にデータを供給するのを終わりにします。エレメント構造を返します。
バージョン 2.7 で撤廃: カスタムの TreeBuilder target で TreeBuilder.doctype() メソッドを 定義してください。
構文解析器にデータを供給します。 data はエンコードされたデータです。
XMLParser.feed() は target の start() メソッドをそれぞれの開始タグに対して呼び、また end() メソッドを終了タグに対して呼び、そしてデータは data() メソッドで処理されます。 XMLParser.close() は target の close() メソッドを呼びます。 XMLParser は木構造を構築する以外にも使えます。以下の例は、XML ファイルの最高の深さを数えます:
>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth: # The target object of the parser
... maxDepth = 0
... depth = 0
... def start(self, tag, attrib): # Called for each opening tag.
... self.depth += 1
... if self.depth > self.maxDepth:
... self.maxDepth = self.depth
... def end(self, tag): # Called for each closing tag.
... self.depth -= 1
... def data(self, data):
... pass # We do not need to do anything with data.
... def close(self): # Called when all data has been parsed.
... return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
... <b>
... </b>
... <b>
... <c>
... <d>
... </d>
... </c>
... </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4
注記
[1] | XML の出力に含まれるエンコーディング文字列は適切な標準に適合していなければなりません。たとえば、”UTF-8” は正当ですが、”UTF8” は違います。 http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl と http://www.iana.org/assignments/character-sets を参照して下さい。 |