tktemplate.py 技術ドキュメント
ライブラリの機能や目的
tktemplate.py は、文字列、ファイル、Excelドキュメントにおける柔軟なテンプレート処理機能を提供するPythonライブラリです。主に以下の目的と機能を持っています。
テンプレートタグの置換:
{{ key }}形式のテンプレートタグを、指定された辞書（コンテキスト）の値で置換します。特殊文字の処理:
\t,\n,\rなどのエスケープシーケンスを実際の特殊文字に変換します。動的な式評価:
@eval:プレフィックスを持つ文字列をPython式として評価し、その結果を適用します。Excelファイルの操作: Excelファイルをテンプレートとして読み込み、データを追加したり、セルの内容を置換したりする機能を提供します。これにより、レポート生成やデータ集計の自動化をサポートします。
数値の安全な変換: 文字列を数値（整数、浮動小数点数）に安全に変換する補助関数を提供します。
科学技術計算支援:
tklib.tksciモジュールから多数の物理定数、数学定数、単位変換関数、数学関数をインポートし、科学技術計算に役立つリソースを一元的に提供します。
このライブラリは、定型的なドキュメントやデータファイルをプログラムから自動生成・更新する際に発生する、データとテンプレートの結合に関する課題を解決することを目的としています。
importする方法
tktemplate.py ライブラリは、標準的なPythonモジュールとして他のスクリプトから import して利用できます。
import tktemplate
または、特定の関数や変数のみをインポートすることも可能です。
from tktemplate import process_template, convert_file, pi
必要な非標準ライブラリとインストール方法
tktemplate.py を利用するためには、以下の非標準ライブラリが必要です。これらは pip コマンドを使用してインストールできます。
numpy: 数値計算のためのライブラリ。
pip install numpy
openpyxl: Excel (.xlsx) ファイルの読み書きのためのライブラリ。
pip install openpyxl
pandas: データ分析と操作のためのライブラリ。DataFrameなど。
pip install pandas
tklib:
tktemplate.pyが依存するカスタムライブラリ。ソースコード上ではtklibから複数のモジュールがインポートされています。tklibは通常、tktemplate.pyと同じ環境か、Pythonのサイトパッケージパスに配置されている必要があります。pipでのインストールが提供されていない場合は、手動で配置するか、パスを設定する必要があります。re: 正規表現モジュールは
process_template関数内で使用されています。Pythonの標準ライブラリの一部であるため、別途インストールする必要はありません。
importできる変数と関数
tktemplate.py を import tktemplate するか、個別に from tktemplate import ... するかで利用できる変数と関数は以下の通りです。
定義済みの関数
pint(s)
文字列を整数に安全に変換します。tklib.tkutils の内部関数 _pint のラッパーです。
動作: 入力文字列
sを整数に変換しようとします。変換できない場合やNoneの場合でもエラーを発生させず、Noneを返します。引数:
s: 変換対象の文字列。
戻り値: 変換された整数、または変換に失敗した場合は
None。
pfloat(s)
文字列を浮動小数点数に安全に変換します。tklib.tkutils の内部関数 _pfloat のラッパーです。
動作: 入力文字列
sを浮動小数点数に変換しようとします。変換できない場合やNoneの場合でもエラーを発生させず、Noneを返します。引数:
s: 変換対象の文字列。
戻り値: 変換された浮動小数点数、または変換に失敗した場合は
None。
process_template(template: str, context: dict) -> str
テンプレート文字列内の特殊文字やテンプレートタグを置換します。
動作:
入力
template文字列内の\t,\n,\rといったエスケープシーケンスを対応する特殊文字に変換します。{{ key }}形式のテンプレートタグをcontext辞書内の対応する値で置換します。キーが見つからない場合は、元のタグ{{ key }}の形式を維持します。
引数:
template(str): テンプレートタグや特殊文字を含む入力文字列。context(dict): テンプレートタグのキーと置換する値のペアを含む辞書。
戻り値: (str) 置換が適用された処理済み文字列。
convert_str(s, replace_dict, blank_nodata = False, print_level = 0)
文字列内のテンプレートタグを置換し、オプションで @eval: プレフィックス付きの式を評価します。
動作:
replace_dictに基づいて、文字列s内の{{ key }}形式のテンプレートタグを対応する値で置換します。blank_nodataがTrueで、置換対象の値がNoneの場合、タグを空文字列に置換します。文字列が
@eval:で始まる場合、その後の部分をPythonの式として評価し、結果を文字列に変換して返します。
引数:
s: 変換対象の文字列。replace_dict:{{ key }}のkeyと置換する値のペアを含む辞書。blank_nodata(bool, オプション):replace_dictの値がNoneの場合にタグを空文字列に置換するかどうか。デフォルトはFalse。print_level(int, オプション): デバッグ出力のレベル。デフォルトは0（出力なし）。
戻り値: 置換および評価が適用された文字列。入力
sがNoneの場合はNone。
convert_file(template_path, output_path, replace_dict, print_level = 0)
テンプレートファイルを読み込み、置換を行い、結果を別のファイルに書き出します。
動作:
template_pathで指定されたテンプレートファイルを読み込みます。各行について、
replace_dictに基づいて{{ key }}形式のタグを置換します。置換後の内容を
output_pathで指定されたファイルに書き込みます。
引数:
template_path: 読み込むテンプレートファイルのパス。output_path: 結果を書き込む出力ファイルのパス。replace_dict:{{ key }}のkeyと置換する値のペアを含む辞書。print_level(int, オプション): デバッグ出力のレベル。デフォルトは0。
戻り値: (bool) ファイル処理が成功した場合は
True、失敗した場合はFalse。
read_template_xlsx(template_path, data_only = False, print_level = 0)
Excelテンプレートファイルを読み込み、最初の2行からラベルとテンプレート文字列を抽出します。
動作:
template_pathで指定されたExcelファイルを読み込みます。アクティブなシートの1行目からラベル（列名）を、2行目からテンプレート文字列を抽出します。
引数:
template_path: 読み込むExcelテンプレートファイルのパス。data_only(bool, オプション): 数式ではなくセルの計算済み値のみを読み込むかどうか。デフォルトはFalse。print_level(int, オプション): デバッグ出力のレベル。デフォルトは0。
戻り値: (tuple)
(labels, templates)のタプル。labelsは1行目の値のリスト、templatesは2行目の値のリスト。ファイルの読み込みに失敗した場合は(None, None)。
replace_df_columns(df, replace_dict, print_level = 0)
Pandas DataFrameの列名を置換します。
動作:
replace_dictのキーと値に基づいて、DataFramedfの列名を変更します。replace_dictにない列名はそのまま維持されます。引数:
df: 置換対象のPandas DataFrame。replace_dict: 古い列名（キー）と新しい列名（値）のペアを含む辞書。print_level(int, オプション): デバッグ出力のレベル。デフォルトは0。
戻り値: 列名が置換されたDataFrame。
add_to_excel(template_path, outfile, data_list, replace_dict, data_only = False, print_level = 1)
Excelテンプレートと辞書データを使用して、既存のExcelファイルにデータを追加します。
動作:
template_pathのExcelテンプレートを読み込み、ヘッダーとテンプレート行を特定します。outfileが存在しない場合は新しいExcelブックを作成し、テンプレートのヘッダーを書き込みます。outfileが存在する場合は、既存のデータに続けて新しい行を追加します。テンプレート行と
replace_dictを使用してデータを変換し、新しい行としてoutfileに書き込みます。
引数:
template_path: Excelテンプレートファイルのパス。outfile: データ追加先のExcelファイルのパス。data_list: 追加するデータのリスト（この関数では使用されていないように見えますが、引数として定義されています）。replace_dict: セルのテンプレートタグを置換するための辞書。data_only(bool, オプション):openpyxl.load_workbookのdata_only引数に渡されます。デフォルトはFalse。print_level(int, オプション): デバッグ出力のレベル。デフォルトは1。
戻り値: (bool) 処理が成功した場合は
True。
read_replacement_db(replacement_db_path, print_level = 1)
Excelファイルから置換ルール（辞書）を読み込みます。
動作:
replacement_db_pathで指定されたExcelファイルを読み込みます。1行目を置換後の文字列（値）、2行目を置換前のラベル（キー）として扱い、それらをマッピングする辞書を生成します。
1行目の最初のセルの値が
@@で終わる場合、その列はスキップされます。
引数:
replacement_db_path: 置換ルールが記述されたExcelファイルのパス。print_level(int, オプション): デバッグ出力のレベル。デフォルトは1。
戻り値: (dict) 置換ルールを含む辞書。
NumPyから直接インポートされた数学関数
以下の関数は、numpy ライブラリから tktemplate.py に直接インポートされており、tktemplate.py モジュールを介して利用できます。これらは標準的な数値計算機能を提供します。
exp: 指数関数 \(e^x\) を計算します。log: 自然対数 \(\ln x\) を計算します。log10: 常用対数 \(\log_{10} x\) を計算します。sin: サイン（正弦）関数 \(\sin x\) を計算します（ラジアン単位）。cos: コサイン（余弦）関数 \(\cos x\) を計算します（ラジアン単位）。tan: タンジェント（正接）関数 \(\tan x\) を計算します（ラジアン単位）。arcsin: アークサイン（逆正弦）関数 \(\arcsin x\) を計算します（ラジアン単位）。arccos: アークコサイン（逆余弦）関数 \(\arccos x\) を計算します（ラジアン単位）。arctan: アークタンジェント（逆正接）関数 \(\arctan x\) を計算します（ラジアン単位）。sqrt: 平方根 \(\sqrt{x}\) を計算します。
tklibモジュールからインポートされたオブジェクトと補助関数
以下のオブジェクトと補助関数は tklib ライブラリから tktemplate.py にインポートされています。
tkObject:tklib.tkobjectモジュールからインポートされた汎用オブジェクトクラス。tkFile:tklib.tkfileモジュールからインポートされたファイル操作を補助するクラス。pconv:tklib.tkutilsモジュールからインポートされた、文字列を適切な型に安全に変換するための補助関数。
tklib.tksciモジュールからインポートされた定数と関数
以下の定数と関数は tklib.tksci.tksci モジュールから tktemplate.py にインポートされており、科学技術計算に役立ちます。
物理定数
h: プランク定数。h_bar/hbar: ディラック定数（換算プランク定数）。 $\( \hbar = \frac{h}{2\pi} \)$e: 電気素量。kB: ボルツマン定数。NA: アボガドロ定数。c: 真空中の光速。me: 電子の静止質量。mp: 陽子の静止質量。mn: 中性子の静止質量。u0: 真空の透磁率。e0: 真空の誘電率。e2_4pie0: クーロン力の定数。a0: ボーア半径。R: 理想気体定数。F: ファラデー定数。g: 標準重力加速度。
数学定数
pi: 円周率 \(\pi\)。pi2: \(2\pi\)。basee: 自然対数の底 \(e\)。
単位変換定数・関数
torad: 度からラジアンへの変換係数 (\( \pi / 180 \))。todeg: ラジアンから度への変換係数 (\( 180 / \pi \))。eVTonm: 電子ボルト (eV) から波長 (nm) への変換関数。nmToeV: 波長 (nm) から電子ボルト (eV) への変換関数。
数学関数（tksci経由）
acos: アークコサイン（逆余弦）関数（ラジアン単位）。asin: アークサイン（逆正弦）関数（ラジアン単位）。atan: アークタンジェント（逆正接）関数（ラジアン単位）。cosh: ハイパボリックコサイン（双曲線余弦）関数。sinh: ハイパボリックサイン（双曲線正弦）関数。tanh: ハイパボリックタンジェント（双曲線正接）関数。degcos: 度数法に対応するコサイン関数。degsin: 度数法に対応するサイン関数。degtan: 度数法に対応するタンジェント関数。degacos: 度数法に対応するアークコサイン関数。degasin: 度数法に対応するアークサイン関数。degatan: 度数法に対応するアークタンジェント関数。factorial: 階乗を計算する関数。Factorize: 数値を素因数分解する関数。Gaussian: ガウス関数を生成する関数。Lorentzian: ローレンツ関数を生成する関数。combination: 組み合わせ \(nCr\) を計算する関数。gamma: ガンマ関数 \(\Gamma(z)\) を計算する関数。
main scriptとして実行したときの動作
tktemplate.py ファイルには if __name__ == "__main__": ブロックが定義されていません。
したがって、このファイルを直接Pythonインタプリタで実行しても、特別な処理は行われません。通常、ライブラリとして他のPythonスクリプトからインポートされ、その機能が利用されることを想定しています。