tktemplate.py ドキュメント

ライブラリの機能や目的

tktemplate.py は、テンプレート処理とExcel連携を提供する多機能モジュールです。

このライブラリの主な目的は、動的なコンテンツ生成をサポートすることにあります。具体的には、文字列、ファイル、Excelデータに対して {{ key }} 形式のテンプレート変数を置換する機能を提供します。これにより、定型的な文書やデータ構造を基に、個別の情報に応じた出力を容易に生成できるようになります。

解決する課題としては、以下のような点が挙げられます。

  • 定型文書のパーソナライズ: レポート、メール、設定ファイルなど、基本的な構造は同じだが一部のデータが異なる文書を効率的に生成できます。

  • Excelデータとの連携: Excelファイルをテンプレートとして利用したり、生成したデータを既存のExcelファイルに追加したりする機能を提供し、データ管理やレポート作成の自動化を支援します。

  • 安全な型変換: 文字列から数値への変換時にエラーが発生しにくいように設計されており、ユーザー入力や外部データソースからの値の処理を安全に行えます。

  • 科学技術計算との統合: tklib.tksci からインポートされる多数の物理定数や数学関数を利用して、テンプレート内で高度な計算結果を組み込むことができます。

importする方法

このライブラリを他のPythonプログラムから利用するには、以下のいずれかの方法でインポートします。

モジュール全体をインポートする場合:

import tktemplate

# 関数の呼び出し例
result = tktemplate.process_template("Hello, {{ name }}!", {"name": "World"})

特定の関数や変数を直接インポートする場合:

from tktemplate import process_template, pi, factorial

# 関数や定数の直接利用例
processed_string = process_template("Value of pi: {{ PI_VAL }}", {"PI_VAL": pi})
fact_5 = factorial(5)

必要な非標準ライブラリとインストール方法

tktemplate.py を実行するためには、以下の非標準ライブラリが必要です。

  • numpy: 高度な数値計算機能を提供します。

  • openpyxl: Excel（.xlsxファイル）の読み書きを可能にします。

  • pandas: データ構造とデータ分析ツールを提供し、特にDataFrame操作に利用されます。

  • tklib: このライブラリが依存するカスタムライブラリです。tktemplate.py は tklib.tkobject, tklib.tkfile, tklib.tkutils, tklib.tksci モジュールを使用しています。

numpy, openpyxl, pandas は pip コマンドでインストールできます。

pip install numpy openpyxl pandas

tklib については、これはこのモジュールが依存するカスタムライブラリであるため、別途入手してPythonの検索パスに配置する必要があります。通常、同じプロジェクト内または仮想環境内にインストールすることで利用可能になります。

importできる変数と関数

tktemplate.py をインポートすると、以下の変数と関数が利用可能になります。

変数（定数）

tklib.tksci.tksci および numpy からインポートされた、物理定数、数学定数、単位変換定数、および数学関数が利用できます。

  • 物理定数:

    • h, h_bar, hbar: プランク定数、換算プランク定数

    • e: 素電荷

    • kB: ボルツマン定数

    • NA: アボガドロ定数

    • c: 光速

    • me, mp, mn: 電子質量、陽子質量、中性子質量

    • u0: 真空の透磁率

    • e0: 真空の誘電率

    • e2_4pie0: \(e^2 / (4 \pi \epsilon_0)\)

    • a0: ボーア半径

    • R: 気体定数

    • F: ファラデー定数

    • g: 標準重力加速度

  • 数学定数:

    • pi: 円周率 (\( \pi \) 約 \(3.14159\))

    • pi2: \(2 \pi\)

    • basee: 自然対数の底 (\(e\) 約 \(2.71828\))

  • 単位変換定数:

    • torad: 度をラジアンに変換する係数

    • todeg: ラジアンを度に変換する係数

    • eVTonm: eVをnmに変換する係数

    • nmToeV: nmをeVに変換する係数

関数

pint(s)

文字列を整数に安全に変換します。

  • 動作: 内部の _pint 関数を呼び出し、デフォルト値なし、厳格でないモードで変換を試みます。

  • 引数:

    • s (str): 整数に変換する入力文字列。

  • 戻り値:

    • int または None: 変換された整数、または変換できなかった場合は None。

pfloat(s)

文字列を浮動小数点数に安全に変換します。

  • 動作: 内部の _pfloat 関数を呼び出し、デフォルト値なし、厳格でないモードで変換を試みます。

  • 引数:

    • s (str): 浮動小数点数に変換する入力文字列。

  • 戻り値:

    • float または None: 変換された浮動小数点数、または変換できなかった場合は None。

process_template(template: str, context: dict) -> str

テンプレート文字列内の特殊文字とタグを置換します。

  • 動作: バックスラッシュでエスケープされたタブ (\t)、改行 (\n)、キャリッジリターン (\r) を実際の特殊文字に置換します。さらに、{{ key }} 形式のテンプレートタグを、context 辞書内の対応する値で置換します。キーが見つからない場合は、元のタグ形式を保持します。

  • 引数:

    • template (str): テンプレートタグと特殊文字を含む入力文字列。

    • context (dict): テンプレート置換のためのキーと値のペアを含む辞書。

  • 戻り値:

    • str: 置換が適用された処理済みの文字列。

convert_str(s, replace_dict, blank_nodata = False, print_level = 0)

文字列内のテンプレートタグを置換し、オプションで式を評価します。

  • 動作: replace_dict に基づいて、入力文字列 s 内の {{key}} 形式のタグを対応する値で置換します。blank_nodata が True の場合、replace_dict 内の値が None であるタグは空文字列に置換されます。文字列が @eval: で始まる場合、その後の文字列はPythonの式として評価され、結果が文字列に変換されます。

  • 引数:

    • s (str or None): 処理する入力文字列。

    • replace_dict (dict): テンプレート置換のためのキーと値のペアを含む辞書。

    • blank_nodata (bool, optional): replace_dict の値が None の場合にタグを空文字列に置換するかどうか。デフォルトは False。

    • print_level (int, optional): デバッグ出力のレベル。0 は出力なし。デフォルトは 0。

  • 戻り値:

    • str or None: 処理された文字列、または入力が None の場合は None。

convert_file(template_path, output_path, replace_dict, print_level = 0)

テンプレートファイルの内容を読み込み、置換を行い、結果を新しいファイルに書き込みます。

  • 動作: template_path で指定されたファイルを読み込み、replace_dict に基づいて各行の {{key}} タグを置換します。処理された内容は output_path で指定されたファイルに書き込まれます。テンプレートファイルが存在しない場合や出力ファイルに書き込めない場合はエラーを報告します。

  • 引数:

    • template_path (str): 読み込むテンプレートファイルのパス。

    • output_path (str): 結果を書き込む出力ファイルのパス。

    • replace_dict (dict): テンプレート置換のためのキーと値のペアを含む辞書。

    • print_level (int, optional): デバッグ出力のレベル。0 は出力なし。デフォルトは 0。

  • 戻り値:

    • bool: ファイル変換が成功した場合は True、失敗した場合は False。

read_template_xlsx(template_path, data_only = False, print_level = 0)

Excelテンプレートファイルからラベルとテンプレート文字列を読み込みます。

  • 動作: 指定されたExcelファイル（template_path）の1行目からラベルを、2行目から対応するテンプレート文字列を読み込みます。data_only が True の場合、セルの表示値（計算結果）を読み込みます。ファイルが存在しない、または読み込めない場合はエラーを報告します。

  • 引数:

    • template_path (str): 読み込むExcelテンプレートファイルのパス。

    • data_only (bool, optional): 数式ではなくセルの計算結果のみを読み込むかどうか。デフォルトは False。

    • print_level (int, optional): デバッグ出力のレベル。0 は出力なし。デフォルトは 0。

  • 戻り値:

    • tuple[list[str], list[str]] or tuple[None, None]: ラベルのリストとテンプレート文字列のリストのタプル。エラーが発生した場合は (None, None)。

replace_df_columns(df, replace_dict, print_level = 0)

DataFrameの列名を指定された辞書に基づいて置換します。

  • 動作: 入力DataFrame df の列名を replace_dict 内のキーと値のペアに基づいて更新します。replace_dict のキーと一致する列名が存在し、かつ replace_dict の値が None または空文字列でない場合に置換が行われます。

  • 引数:

    • df (pandas.DataFrame): 列名を置換する対象のDataFrame。

    • replace_dict (dict): 列名の置換ルールを含む辞書。キーが元の列名、値が新しい列名。

    • print_level (int, optional): デバッグ出力のレベル。0 は出力なし。デフォルトは 0。

  • 戻り値:

    • pandas.DataFrame: 列名が置換されたDataFrame。

add_to_excel(template_path, outfile, data_list, replace_dict, data_only = False, print_level = 1)

Excelテンプレートから構造を読み込み、新しいデータをExcelファイルに追加します。

  • 動作: template_path からExcelテンプレートを読み込み、既存または新規の outfile にデータを追加します。テンプレートの2行目の内容（テンプレート文字列）を replace_dict と data_list を使用して変換し、outfile の最終行に書き込みます。出力ファイルが存在しない場合は新規に作成し、テンプレートの1行目（ラベル）をヘッダーとして書き込みます。

  • 注意: この関数内で呼び出されている convert_by_template は、この tktemplate.py モジュール内で定義されていません。そのため、実行時に NameError を発生させる可能性があります。また、data_list 引数は現在の実装では使用されていません。さらに、print_lvelというタイプミスがあります。

  • 引数:

    • template_path (str): 読み込むExcelテンプレートファイルのパス。

    • outfile (str): データを追加するExcelファイルのパス。存在しない場合は新規作成されます。

    • data_list (list): (現在未使用) 追加するデータのリスト。

    • replace_dict (dict): テンプレート置換のためのキーと値のペアを含む辞書。

    • data_only (bool, optional): テンプレート読み込み時に数式ではなくセルの計算結果のみを読み込むかどうか。デフォルトは False。

    • print_level (int, optional): デバッグ出力のレベル。1 は基本情報、2 は詳細情報。デフォルトは 1。

  • 戻り値:

    • bool: データ追加処理が成功した場合は True。

read_replacement_db(replacement_db_path, print_level = 1)

Excelファイルから置換ルール（キーと置換文字列）を読み込み、辞書として返します。

  • 動作: 指定されたExcelファイル（replacement_db_path）の1行目から置換文字列を、2行目からラベル（キー）を読み込みます。これらの情報から、{{key}} タグを置換文字列 value で置換するための辞書 replace_dict を作成します。ただし、1行目1列目の値が @@ で終わる場合は、その列はスキップされます。

  • 引数:

    • replacement_db_path (str): 置換ルールを含むExcelファイルのパス。

    • print_level (int, optional): デバッグ出力のレベル。1 は基本情報、2 は詳細情報。デフォルトは 1。

  • 戻り値:

    • dict: ラベルをキー、置換文字列を値とする辞書。

数学・科学技術計算関数

numpy および tklib.tksci.tksci からインポートされた以下の関数も直接利用できます。

  • NumPy由来: exp, log, log10, sin, cos, tan, arcsin, arccos, arctan, sqrt

  • tklib.tksci由来:

    • 三角関数・双曲線関数: acos, asin, atan, cosh, sinh, tanh

    • 度数指定三角関数: degcos, degsin, degtan, degacos, degasin, degatan

    • その他: factorial (階乗), Factorize (素因数分解), Gaussian (ガウス関数), Lorentzian (ローレンツ関数), combination (組み合わせ), gamma (ガンマ関数)

main scriptとして実行したときの動作

tktemplate.py のソースコードには、if __name__ == "__main__": ブロックが存在しません。 したがって、このライブラリファイルが単体でPythonインタプリタによって直接実行されたとしても、特別なスクリプトとしての動作は定義されていません。通常、他のプログラムからモジュールとしてインポートされ、その中に定義された関数や変数を利用することが意図されています。