tktemplate プログラム仕様

概要: テンプレート処理とExcel連携を提供するモジュール。

詳細説明: このモジュールは、文字列、ファイル、Excelデータに対するテンプレート変数の置換機能や、 Excelファイルへのデータ追加機能を提供します。 {{ key }}形式のテンプレートタグを使用して、動的なコンテンツ生成をサポートします。

関連リンク:

tktemplate_usage

tklib.tktemplate.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関数は、このモジュール内で定義されていないため、実行時にエラーを発生させる可能性があります。

引数:

param template_path:

読み込むExcelテンプレートファイルのパス。

type template_path:

str

param outfile:

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

type outfile:

str

param data_list:

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

type data_list:

list

param replace_dict:

テンプレート置換のためのキーと値のペアを含む辞書。

type replace_dict:

dict

param data_only:

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

type data_only:

bool, optional

param print_level:

デバッグ出力のレベル。1は基本情報、2は詳細情報。デフォルトは1。

type print_level:

int, optional

戻り値:

returns:

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

rtype:

bool

tklib.tktemplate.convert_file(template_path, output_path, replace_dict, print_level=0)

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

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

引数:

param template_path:

読み込むテンプレートファイルのパス。

type template_path:

str

param output_path:

結果を書き込む出力ファイルのパス。

type output_path:

str

param replace_dict:

テンプレート置換のためのキーと値のペアを含む辞書。

type replace_dict:

dict

param print_level:

デバッグ出力のレベル。0は出力なし。デフォルトは0。

type print_level:

int, optional

戻り値:

returns:

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

rtype:

bool

tklib.tktemplate.convert_str(s, replace_dict, blank_nodata=False, print_level=0)

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

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

引数:

param s:

処理する入力文字列。

type s:

str or None

param replace_dict:

テンプレート置換のためのキーと値のペアを含む辞書。

type replace_dict:

dict

param blank_nodata:

replace_dictの値がNoneの場合にタグを空文字列に置換するかどうか。デフォルトはFalse。

type blank_nodata:

bool, optional

param print_level:

デバッグ出力のレベル。0は出力なし。デフォルトは0。

type print_level:

int, optional

戻り値:

returns:

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

rtype:

str or None

tklib.tktemplate.pfloat(s)

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

詳細説明: 内部の _pfloat 関数を呼び出し、デフォルト値なし、厳格でないモードで変換を試みます。 変換できない場合は None を返します。

引数:

param s:

浮動小数点数に変換する入力文字列。

type s:

str

戻り値:

returns:

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

rtype:

float or None

tklib.tktemplate.pint(s)

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

詳細説明: 内部の _pint 関数を呼び出し、デフォルト値なし、厳格でないモードで変換を試みます。 変換できない場合は None を返します。

引数:

param s:

整数に変換する入力文字列。

type s:

str

戻り値:

returns:

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

rtype:

int or None

tklib.tktemplate.process_template(template: str, context: dict) → str

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

詳細説明: バックスラッシュでエスケープされたタブ ( )、改行 (

)、キャリッジリターン ( ) を

実際の特殊文字に置換します。 さらに、{{ key }}形式のテンプレートタグを、context辞書内の対応する値で置換します。 キーが見つからない場合は、元のタグ形式を保持します。

引数:

param template:

テンプレートタグと特殊文字を含む入力文字列。

type template:

str

param context:

テンプレート置換のためのキーと値のペアを含む辞書。

type context:

dict

戻り値:

returns:

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

rtype:

str

tklib.tktemplate.read_replacement_db(replacement_db_path, print_level=1)

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

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

引数:

param replacement_db_path:

置換ルールを含むExcelファイルのパス。

type replacement_db_path:

str

param print_level:

デバッグ出力のレベル。1は基本情報、2は詳細情報。デフォルトは1。

type print_level:

int, optional

戻り値:

returns:

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

rtype:

dict

tklib.tktemplate.read_template_xlsx(template_path, data_only=False, print_level=0)

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

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

引数:

param template_path:

読み込むExcelテンプレートファイルのパス。

type template_path:

str

param data_only:

数式ではなくセルの計算結果のみを読み込むかどうか。デフォルトはFalse。

type data_only:

bool, optional

param print_level:

デバッグ出力のレベル。0は出力なし。デフォルトは0。

type print_level:

int, optional

戻り値:

returns:

ラベルのリストとテンプレート文字列のリストのタプル。エラーが発生した場合は(None, None)。

rtype:

tuple[list[str], list[str]] or tuple[None, None]

tklib.tktemplate.replace_df_columns(df, replace_dict, print_level=0)

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

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

引数:

param df:

列名を置換する対象のDataFrame。

type df:

pandas.DataFrame

param replace_dict:

列名の置換ルールを含む辞書。キーが元の列名、値が新しい列名。

type replace_dict:

dict

param print_level:

デバッグ出力のレベル。0は出力なし。デフォルトは0。

type print_level:

int, optional

戻り値:

returns:

列名が置換されたDataFrame。

rtype:

pandas.DataFrame