tkxml.py 技術ドキュメント
ライブラリの機能や目的
tkxml.py は、XMLデータの解析、変換、操作を支援するPythonユーティリティライブラリです。
このモジュールの主な目的は、Python標準ライブラリである xml.etree.ElementTree や xml.dom.minidom に加え、外部ライブラリの xmltodict、dicttoxml、numpy を利用して、XMLファイルとPythonの辞書構造間の相互変換、XML要素の再帰的な解析、特定のセクション情報の抽出、整形されたXMLの書き出しなど、XML操作に関する幅広い機能を提供することです。
具体的には、ATLAS最適化XMLやVASP計算結果XML (vasprun.xml) などの特定のフォーマットを持つXMLファイルの解析を容易にする機能を含んでいます。これにより、これらの複雑なXML構造から必要な情報を効率的に抽出し、Pythonプログラム内で扱いやすい形式に変換することが可能になります。
importする方法
tkxml.py ライブラリを他のPythonプログラムからインポートするには、以下のいずれかの方法を使用します。
ライブラリ全体をインポートする場合:
import tkxml
特定の関数のみをインポートする場合:
from tkxml import get_root, file2dict, dict2xml
必要な非標準ライブラリとインストール方法
tkxml.py が依存する非標準ライブラリは以下の通りです。
xmltodict: XMLをPythonの辞書に変換するために使用されます。dicttoxml: Pythonの辞書をXMLに変換するために使用されます。numpy: 数値計算機能を提供しますが、このライブラリの主なXML処理機能では直接的に利用されていないようです。ただし、依存関係として含まれています。
これらのライブラリは pip コマンドを使用してインストールできます。
pip install xmltodict dicttoxml numpy
importできる変数と関数
変数
infile: デフォルトの入力ファイルパスとして'opt_2onl.xml'が設定されています。スクリプトがコマンドライン引数付きで実行された場合、この変数の値は最初のコマンドライン引数によって上書きされます。
関数
get_elements_recursive(element)動作: XML要素の子要素の情報を再帰的に取得します。入力されたXML要素が子要素を持たない場合、その要素のテキスト内容を返します。子要素を持つ場合、各子要素のタグ、テキスト、属性を抽出し、さらにその子要素に対して再帰的にこの関数を呼び出して情報を収集します。収集された情報は、辞書のリストとして返されます。 引数:element: 処理対象のxml.etree.ElementTree.Elementオブジェクト。 戻り値:子要素がない場合は要素のテキスト (
str)。子要素がある場合は子要素情報のリスト (
list[dict])。
get_unique_key(d, section, val = None)動作: 辞書d内でユニークなキー名を生成します。指定されたsectionとvalに基づいてキーを生成し、辞書dにそのキーが存在しない場合はそのまま返します。既に存在する場合は、section[i]:valまたはsection[i]の形式でインデックスを付加し、ユニークなキーが見つかるまで試行します。 引数:d: キーの存在を確認する辞書。section: キーの基本となるセクション名。val: (オプション) セクションに付加する値。デフォルトはNone。 戻り値:辞書内でユニークなキー文字列 (
str)。
get_section_inf(parent, sections = None, inf = None, params = None, ret_type = 'list', add_parent_params = True)動作: 指定されたセクションパスに沿ってXML要素の情報を取得します。parent要素からsectionsリストで指定されたパスを辿り、最後のセクションの子要素の情報を取得します。ret_typeが'list'の場合はリストで、'dict'の場合は辞書で情報を返します。途中の親要素の属性もparams_childとして収集され、add_parent_paramsがTrueの場合、最終的な戻り値に含められます。 引数:parent: 検索を開始するxml.etree.ElementTree.Elementオブジェクト。sections: (オプション) 検索する子要素のタグ名のリスト。デフォルトはNone。inf: (オプション) 情報を追加する既存のリストまたは辞書。関数内でコピーして使用されます。デフォルトはNone。params: (オプション) 親要素から引き継がれるパラメータの辞書。デフォルトはNone。ret_type: (オプション) 戻り値の型 ('list'または'dict')。デフォルトは'list'。add_parent_params: (オプション) 親のパラメータを戻り値に含めるかどうか。デフォルトはTrue。 戻り値:子要素のタグ、テキスト、属性、または子要素の属性情報を含む辞書/リスト。
get_section_inf_all(parent, sections = None, section_parent = 'root', inf = None, level = 0, params = None, pkey = None, ret_type = 'list', last_node_only = True)動作: 指定されたセクションパスに沿ってXML要素の情報を再帰的に取得します。parent要素からsectionsリストで指定されたパスを辿り、各階層の子要素の情報を取得します。last_node_onlyがFalseの場合、中間ノードの情報も収集します。ret_typeが'list'の場合はリストで、'dict'の場合は辞書で情報を返します。親要素の属性はparams_childとして引き継がれ、各ノードの情報に含まれます。 引数:parent: 検索を開始するxml.etree.ElementTree.Elementオブジェクト。sections: (オプション) 検索する子要素のタグ名のリスト。デフォルトはNone。section_parent: (オプション) 現在のparent要素のタグ名（ユニークキー生成用）。デフォルトは'root'。inf: (オプション) 情報を追加する既存のリストまたは辞書。デフォルトはNone。level: (オプション) 現在の再帰レベル。デフォルトは0。params: (オプション) 親要素から引き継がれるパラメータの辞書。デフォルトはNone。pkey: (オプション)ret_typeが'dict'の場合にキーとして使用する属性名。デフォルトはNone。ret_type: (オプション) 戻り値の型 ('list'または'dict')。デフォルトは'list'。last_node_only: (オプション) 最後のセクションのノードのみを収集するか、すべてのノードを収集するか。デフォルトはTrue。 戻り値:子要素のタグ、テキスト、属性、および親要素のパラメータを含む辞書/リスト。
xml2dict(xml)動作: XML文字列またはElementTree要素を辞書に変換します。xmltodictライブラリを使用して、入力されたXMLデータをPythonの辞書構造に変換します。 引数:xml: 変換するXML文字列。 戻り値:変換された辞書。
_element_to_dict(element)(内部関数) 動作:xml.etree.ElementTreeのElementオブジェクトを再帰的に辞書に変換します。要素の属性は'@attributes'キーの下に、テキスト内容は'#text'キーの下に格納されます。同じタグ名の子要素が複数ある場合はリストとして扱われます。これはxmltodictの代替または補助的な役割を果たす内部関数であり、通常は直接使用されません。 引数:element: 変換するxml.etree.ElementTree.Elementオブジェクト。 戻り値:変換された辞書。
file2dict(infile)動作: 指定されたファイルパスのXMLファイルを読み込み、辞書に変換します。指定されたパスからXMLファイルを読み込み、その内容をxml2dict関数を使って辞書形式に変換します。 引数:infile: 読み込むXMLファイルのパス。 戻り値:変換された辞書。
dict2xml(d, attr_type = True, root = True)動作: 辞書をXMLインスタンスに変換します。dicttoxmlライブラリを使用して、入力されたPythonの辞書をXMLインスタンスに変換します。 引数:d: 変換する辞書。attr_type: (オプション) 辞書のキーをXMLタグの属性として扱うかどうか。デフォルトはTrue。root: (オプション) 生成されるXMLにルート要素を含めるかどうか。デフォルトはTrue。 戻り値:変換されたXMLインスタンス (
bytes)。
to_xml(outfile, element, encoding = 'utf-8', newl = '', indent = '', addindent = ' ', xml_declaration = True, use_minidom = False)動作: XML要素をファイルに書き出します。use_minidomがTrueの場合、xml.dom.minidomを使用してXMLを整形（インデントと改行を追加）してファイルに書き出します。それ以外の場合は、xml.etree.ElementTreeを使用して直接書き出します。 引数:outfile: 書き込み先のファイルパス。element: 書き出すルートのxml.etree.ElementTree.Elementオブジェクト。encoding: (オプション) 出力ファイルのエンコーディング。デフォルトは'utf-8'。newl: (オプション)use_minidomがTrueの場合の改行文字。デフォルトは''。indent: (オプション)use_minidomがTrueの場合のインデント文字列。デフォルトは''。addindent: (オプション)use_minidomがTrueの場合の追加インデント文字列。デフォルトは' '。xml_declaration: (オプション) XML宣言 (<?xml version="...">) を含めるかどうか。デフォルトはTrue。use_minidom: (オプション)xml.dom.minidomを使用してXMLを整形するかどうか。デフォルトはFalse。 戻り値:None
get_attrib(element)動作: XML要素のタグ、テキスト、および属性を取得します。 引数:element: 処理対象のxml.etree.ElementTree.Elementオブジェクト。 戻り値:要素のタグ (
str)、テキスト内容 (str)、属性の辞書 (dict)。
get_root(xml)動作: XMLソースからルート要素を取得します。入力がファイルパスの場合はファイルを解析し、XML文字列の場合は文字列から解析してxml.etree.ElementTree.Element型のルート要素を返します。 引数:xml: XMLファイルのパス (str) またはXML文字列 (str)。 戻り値:xml.etree.ElementTree.Element型のXMLルート要素。
main()(メイン実行関数) 動作: スクリプトが直接実行された際に呼び出されるメイン関数です。コマンドライン引数から入力ファイルを読み込み、そのXML構造に基づいてATLAS最適化XMLまたはVASP計算結果XML (vasprun.xml) を解析し、関連情報を標準出力に出力します。解析対象のXMLタイプが判別できない場合はエラーメッセージを出力して終了します。 引数:なし 戻り値:
None
main scriptとして実行したときの動作
tkxml.py がメインスクリプトとして実行された場合 (python tkxml.py のように実行)、if __name__ == '__main__': ブロックが実行され、その中で main() 関数が呼び出されます。
main() 関数の主な動作は以下の通りです。
入力ファイルの指定:
デフォルトの入力ファイルは
infile変数に設定されている'opt_2onl.xml'です。コマンドライン引数がある場合 (
python tkxml.py my_xml_file.xmlのように実行)、最初の引数がinfileの値として使用されます。
XMLルート要素の取得:
指定された
infileからget_root()関数を使ってXMLのルート要素が取得されます。
XMLタイプの判別と解析:
取得したルート要素に対して、特定のXPath (
.//parameter-listまたは.//incar) を使ってXMLのタイプを判別します。ATLAS最適化XMLの場合: ルート要素内に
parameter-listが見つかった場合、ATLAS最適化XMLと判断されます。parameter-listセクションからparameter情報をget_section_inf_all()を使って辞書形式で抽出・表示します。settingsセクションからsetting情報を同様に抽出・表示します。target-listセクションからtarget情報を同様に抽出・表示します。
VASP計算結果XML (vasprun.xml) の場合: ルート要素内に
incarが見つかった場合、vasprun.xmlと判断されます。projected_kpoints_opt、eigenvalues、set、rなどを含むパスからバンド情報をget_section_inf_all()を使って抽出・表示します。incarセクションからその子要素の情報をget_section_inf_all()を使って辞書形式で抽出し、表示します。
その他のXMLタイプの場合: 上記のいずれのタイプにも合致しない場合、「Error: Invalid XML type」というメッセージを出力し、スクリプトは終了します。
解析結果はすべて標準出力に表示されます。