tkapplication プログラム仕様

概要: コマンドラインアプリケーションやGUIアプリケーションの共通機能を提供するモジュール。 詳細説明: このモジュールは、アプリケーション開発における共通のタスクを効率的に処理するための基底クラス tkApplication を定義します。

これには、コマンドライン引数の解析、設定ファイルの管理、標準出力およびエラー出力のリダイレクト、 例外ハンドリングのカスタマイズ、プラグインモジュールの動的ロード、実行時間の計測などが含まれます。 アプリケーションは tkApplication を継承することで、これらの豊富なユーティリティをすぐに利用できます。

関連リンク: tklib.tkapplication_usage

tklib.tkapplication.main()

概要: モジュールが直接実行された場合に呼び出されるメイン関数。

詳細説明:

このモジュールがライブラリとして設計されているため、直接実行された場合には、 それがライブラリであり実行可能ではないことを示すメッセージを出力します。

戻り値:

None.

tklib.tkapplication.save_fit_config(vars, outfile, labels=['varname', 'unit', 'pk_scale', 'optid', 'x0', 'dx', 'kmin', 'kmax', 'kpenalty'], section='Parameters')

概要: フィッティング設定をファイルに保存する。

詳細説明:

`vars`オブジェクトから指定されたラベルのデータを抽出し、CSVまたはExcel形式で出力します。 出力ファイルの種類は、`outfile`の拡張子によって自動的に判別されます。 この関数は、フィッティングパラメータの構成をテンプレートとして保存するために利用できます。

パラメータ:

• vars -- tkParams or similar. 保存する変数群を含むオブジェクト。

• outfile -- str. 出力ファイルパス。拡張子 (.csv, .xlsx) に応じてファイル形式が決定されます。

• labels -- list[str]. `vars`オブジェクトから取得する属性名のリスト。

• section -- str. 設定ファイル内のセクション名。CSV/Excel出力では直接使用されません。

戻り値:

None or tkVariousData().saveの戻り値. 保存が成功した場合は`tkVariousData().save`関数の結果、それ以外は`None`。

class tklib.tkapplication.tkApplication(usage_str='', suppress_usage='', _globals=None, locals=None, use_user_inifile=False, inifile_dirs=['ini'], create_inidir=False, save_time=True, **args)

ベースクラス: tkObject

概要: コマンドラインアプリケーションやGUIアプリケーションの共通機能を管理する基底クラス。

詳細説明:

このクラスは、Pythonアプリケーションの基本的な構造と共通ユーティリティを提供します。 具体的には、以下の機能が含まれます。 - OS情報やスクリプト実行パスの取得 - コマンドライン引数の解析と管理 - INIファイルによる設定の読み書き - 標準出力および標準エラー出力のリダイレクト機能 - 例外ハンドリングのカスタマイズ（カラー表示対応） - 実行時間の計測と表示 - プラグインモジュールの動的ロードと呼び出し - 多言語リソースの管理と表示 `tkApplication`を継承することで、これらの機能を手間なくアプリケーションに統合できます。

パラメータ:

• usage_str -- str. アプリケーションの用法説明として使用する文字列。

• suppress_usage -- str. 用法説明の一部または全部を抑制するためのキーワード（例: 'all', 'usage', 'options'）。

• _globals -- dict. グローバル変数辞書。通常は`globals()`を渡します。

• locals -- dict. ローカル変数辞書。通常は`locals()`を渡します。

• use_user_inifile -- bool. ユーザー固有のINIファイル（ユーザー名を含む）を使用するかどうか。

• inifile_dirs -- list[str]. INIファイルを検索するディレクトリのリスト。

• create_inidir -- bool. INIファイルディレクトリが存在しない場合に作成するかどうか。

• save_time -- bool. 起動時間や経過時間を記録するかどうか。

• args -- dict. `tkObject`のコンストラクタに渡される追加引数。

add_argument(opt=None, opt_str=None, var_name=None, desc=None, type='str', defval=None, optional=True)

概要: アプリケーションにコマンドライン引数を追加する。

詳細説明:

位置引数またはキーワード引数の定義をアプリケーションの引数情報辞書 （self.args_idx_inf`または`self.args_opt_inf）に追加します。 これにより、read_args`メソッドがこれらの引数を認識し、解析できるようになります。 `opt_str`や`var_name、`desc`が`None`の場合、適切なデフォルト値が自動生成されます。

パラメータ:

• opt -- str or None. キーワード引数のオプション文字列（例: '--help'）。位置引数の場合は`None`。

• opt_str -- str or None. 引数の使用法を示す文字列（例: '--infile=path'）。`None`の場合、自動生成されます。

• var_name -- str or None. 引数に対応する変数名。`None`の場合、`opt`から自動生成されます。

• desc -- str or None. 引数の説明。`None`の場合、`var_name`が使用されます。

• type -- str. 引数の型（例: 'str', 'int', 'float'）。`pconv_by_type`による型変換に使用されます。

• defval -- any. 引数のデフォルト値。

• optional -- bool. 引数がオプションであるかどうか。`True`の場合、指定されなくてもエラーになりません。

戻り値:

tuple[dict, list]. (キーワード引数情報辞書, 位置引数情報リスト)。

analyze_infile(path, infile_ext=[], config_ext=[], print_level=1)

概要: 入力ファイルパスを解析し、それがデータファイルか設定ファイルかを判断する。

詳細説明:

指定されたファイルパスの拡張子を、既知の入力ファイル拡張子リストと設定ファイル拡張子リストと比較します。 - パスが`config_ext`のいずれかの拡張子を持つ場合、そのパスは設定ファイルとみなされます。 - パスが`infile_ext`のいずれかの拡張子を持つか、またはその他の拡張子を持つ場合、そのパスは入力ファイルとみなされ、

対応する設定ファイルパスが`config_ext`の最初の拡張子を使って生成されます。

パラメータ:

• app -- tkApplication. アプリケーションインスタンス。

• path -- str. 解析対象のファイルパス。

• infile_ext -- list[str]. 入力ファイルとして認識する拡張子のリスト（例: ['.csv', '.txt']）。

• config_ext -- list[str]. 設定ファイルとして認識する拡張子のリスト（例: ['.ini', '.cfg']）。

• print_level -- int. 解析結果の表示レベル。0の場合、メッセージは表示されません。

戻り値:

tuple[str or None, str, str or None]. (infile: 入力ファイルパスまたは`None` (設定ファイルの場合),

config_path: 設定ファイルパス, infile_stored: 入力ファイルパス（内部保存用）または`None` (設定ファイルの場合))

call(module_name, func_name, *args, **kwargs)

概要: ロードされたプラグインモジュール内の関数、またはグローバルスコープの関数を呼び出す。

詳細説明:

`self.modules`リスト内で指定された`module_name`を持つモジュールを検索し、 そのモジュール内に指定された`func_name`が存在すれば呼び出します。 モジュール内に見つからない場合や、`module_name`が文字列でない場合は、 `self.globals`から`func_name`を検索して呼び出します。 関数が見つからない場合はアプリケーションを終了します。

パラメータ:

• module_name -- str or module. 呼び出す関数を含むモジュールの名前またはモジュールオブジェクト。

• func_name -- str. 呼び出す関数の名前。

• args -- tuple. 関数に渡される位置引数。

• kwargs -- dict. 関数に渡されるキーワード引数。

戻り値:

any. 呼び出された関数の戻り値。

例外:

SystemExit -- 指定された関数が見つからない場合、アプリケーションを終了します。

call_all(func_name, *args)

概要: ロードされたすべてのプラグインモジュール内の特定の関数を呼び出す。

詳細説明:

`self.modules`リスト内のすべてのモジュールを反復処理し、 指定された`func_name`を持つ関数が存在する場合にそれを呼び出します。 関数が複数のモジュールに存在する場合、呼び出しは実行されますが、 最後に呼び出された関数の戻り値のみが返されます。 いずれのモジュールにも見つからない場合は、`self.globals`から関数を呼び出します。

パラメータ:

• func_name -- str. 呼び出す関数の名前。

• args -- tuple. 関数に渡される位置引数。

戻り値:

any. 最後に呼び出された関数の戻り値、または関数が見つからなかった場合は`None`。

check_arg(varname, defval=None, vartype='str')

概要: コマンドライン引数の存在と値をチェックする。

詳細説明:

sys.argv`を走査し、指定された変数名（キーワード引数）または位置インデックス（位置引数）に 対応する引数を検索します。 - 引数が見つかった場合、その値が`vartype`で指定された型に変換されて返されます。 - 引数が--key`のように値なしで与えられた場合は`False`を返します。 - 引数が見つからなかった場合、defval`を返します。 引数の定義情報（`self.args_opt_inf）が存在する場合、そのデフォルト値が`defval`として優先されます。

パラメータ:

• varname -- str or int. チェックしたい引数の変数名または位置インデックス。

• defval -- any. 引数が見つからなかった場合のデフォルト値。

• vartype -- str. 期待される引数の型（例: 'str', 'int', 'float'）。

戻り値:

any or bool. 引数の値（型変換後）、`False`（キーのみの場合）、またはデフォルト値。

check_help(pause=True)

概要: コマンドライン引数にヘルプオプションが含まれているかをチェックし、含まれていれば用法説明を表示して終了する。

詳細説明:

sys.argv`を走査し、--help`, -?, /?, ?, `help`のいずれかの引数が見つかった場合、 `usage`メソッドを呼び出してアプリケーションの用法説明を表示し、アプリケーションを終了します。

パラメータ:

pause -- bool. 用法説明表示後に終了する前にユーザー入力で一時停止するかどうか。

戻り値:

None. (ヘルプ引数が見つかった場合、アプリケーションは終了するため、通常の戻り値はありません)。

daemonize(stdin_path='/dev/null', stdout_path='/dev/null', stderr_path='/dev/null', print_level=0)

概要: 現在のプロセスをデーモン化する。

詳細説明:

現在のプロセスをバックグラウンドで実行されるデーモンプロセスに変換します。 標準入力、標準出力、標準エラー出力は、それぞれ指定されたファイルにリダイレクトされます。 このメソッドはPOSIX（Unix系）オペレーティングシステムでのみ有効です。 2段階のforkと`os.setsid()`により、親プロセスから完全に分離されます。

パラメータ:

• stdin_path -- str. 標準入力のリダイレクト先ファイルパス。

• stdout_path -- str. 標準出力のリダイレクト先ファイルパス。

• stderr_path -- str. 標準エラー出力のリダイレクト先ファイルパス。

• print_level -- int. デーモン化処理に関するメッセージの表示レベル。0の場合、メッセージは表示されません。

戻り値:

None.

exception_hook(type, value, tb, output='stderr', display_type='colored', pause_at_terminate=True)

概要: 未処理の例外を捕捉し、指定された形式で出力するフック関数。

詳細説明:

`sys.excepthook`に設定されることを想定した関数です。 トレースバックをカラー表示（`pygments`が利用可能な場合）またはプレーンテキストで、 指定された出力先（標準エラーまたは標準出力）に書き出します。 また、アプリケーション終了時にユーザー入力で一時停止するかどうかも設定できます。

パラメータ:

• type -- type. 例外の型（例: ValueError, TypeError）。

• value -- Exception. 例外インスタンス。

• tb -- traceback. 例外のトレースバックオブジェクト。

• output -- str. トレースバックの出力先 ('stderr' または 'stdout')。

• display_type -- str. トレースバックの表示形式 ('colored' または 'plain')。

• pause_at_terminate -- bool. 終了時にユーザー入力で一時停止するかどうか。

戻り値:

None.

force_given_args(cparams)

概要: コマンドラインで与えられた引数を指定されたパラメータオブジェクトに強制的に設定する。

詳細説明:

read_args`メソッドで解析された引数（`self.given_args、self.args_idx）を、 tkParams`などのパラメータオブジェクト（`cparams）の属性として直接設定します。 これにより、コマンドライン引数が他の設定よりも優先される形でパラメータが更新されます。

パラメータ:

cparams -- tkParams. 引数の値を設定するターゲットパラメータオブジェクト。

戻り値:

None.

get_args()

概要: コマンドライン引数を取得する。

詳細説明:

Pythonスクリプト実行時に渡されたコマンドライン引数のリストと、その引数の数を返します。 リストの最初の要素は常にスクリプトファイル名です。

戻り値:

tuple[list[str], int]. (引数リスト, 引数の数)。

get_argv()

概要: コマンドライン引数を取得する。

詳細説明:

`get_args`メソッドと同じく、Pythonスクリプト実行時に渡されたコマンドライン引数のリストと、 その引数の数を返します。

戻り値:

tuple[list[str], int]. (引数リスト, 引数の数)。

get_inifile_dir(use_user_inifile=False, inifile_dirs=['ini'], create_inidir=False, defval=None)

概要: INIファイルが配置されるディレクトリのパスを取得する。

詳細説明:

ユーザー固有のINIファイルを使用するかどうか、INIファイルを検索するディレクトリのリスト、 およびディレクトリが存在しない場合に作成するかどうかに基づいて、 適切なINIファイルディレクトリを決定して返します。

パラメータ:

• use_user_inifile -- bool. ユーザー固有のINIファイルディレクトリを使用するかどうか。

• inifile_dirs -- list[str]. INIファイルディレクトリの候補リスト。優先度の高い順に指定します。

• create_inidir -- bool. ディレクトリが存在しない場合に作成するかどうか。`True`の場合、最初の候補ディレクトリを作成します。

• defval -- str. 候補ディレクトリが見つからなかった場合のデフォルト値。

戻り値:

str. INIファイルディレクトリの絶対パス。

get_inifile_path(inidir, use_user_inifile=False)

概要: アプリケーションのINIファイルパスを生成する。

詳細説明:

スクリプトのファイル名（拡張子なし）とINIファイルディレクトリ、 ユーザー固有の設定を使用するかどうかに基づいて、INIファイルの完全なパスを構築して返します。 `use_user_inifile`が`True`の場合、ファイル名に現在のユーザー名が追加されます。

パラメータ:

• inidir -- str. INIファイルが配置されるディレクトリのパス。

• use_user_inifile -- bool. ユーザー固有のINIファイルを使用するかどうか。`True`の場合、ユーザー名がファイル名に追加されます。

戻り値:

str. 生成されたINIファイルの絶対パス。

get_param_dic()

概要: アプリケーションのパラメータを内部辞書形式で取得する。

詳細説明:

self.params`オブジェクトの内部辞書（`__dict__）を直接返します。 これは、`tkParams`インスタンスが保持するすべての属性を辞書として見たい場合に便利です。

戻り値:

dict. パラメータの内部辞書。

get_param_dict()

概要: アプリケーションのパラメータを辞書形式で取得する。

詳細説明:

`self.params`オブジェクトが保持するパラメータを辞書として返します。 これは`tkParams`オブジェクトの`get_param_dict`メソッドを呼び出すものです。

戻り値:

dict. パラメータの辞書。

get_params()

概要: アプリケーションのパラメータオブジェクトを取得する。

詳細説明:

`self.params`に格納されている`tkParams`インスタンスを返します。 このオブジェクトは、アプリケーション全体で共有される設定やデータを管理するために使用されます。

戻り値:

tkParams. アプリケーションのパラメータオブジェクト。

getarg(varname, defval=None, vartype='str')

概要: コマンドライン引数を変数名、デフォルト値、および型指定で取得する。

詳細説明:

sys.argv`を走査し、指定された変数名（キーワード引数）または位置インデックス（位置引数）に 対応する引数の値を取得します。 取得した値は`vartype`で指定された型に変換されます。 引数が--key`のように値なしで与えられた場合は`1`を返します。 引数が見つからなかった場合、`defval`を返します。

パラメータ:

• varname -- str or int. 取得したい引数の変数名（キー）または位置インデックス。

• defval -- any. 引数が見つからなかった場合のデフォルト値。

• vartype -- str. 取得する値の型（例: 'str', 'int', 'float'）。`pconv_by_type`に渡されます。

戻り値:

any. 見つかった引数の値（指定された型に変換後）、またはデフォルト値。

load_module(module_name, target='', plugin_dir='', desc='', ret_type='module', is_print=False)

概要: 指定されたモジュールを動的にロードする。

詳細説明:

`importlib.import_module`を使用して、指定された名前のPythonモジュールをロードします。 `plugin_dir`が指定されていれば、`sys.path`に追加されます。 ロードされたモジュールは、`tkModule`オブジェクトとしてラップされ、`self.modules`リストに保存されます。 ロードに失敗した場合、警告メッセージが出力され、`None`が返されます。

パラメータ:

• module_name -- str. ロードするモジュールの名前。

• target -- str. モジュールが対象とする機能（例: 'read_data'）。

• plugin_dir -- str. モジュールが配置されているディレクトリ。このパスは`sys.path`に追加されます。

• desc -- str. モジュールの説明。

• ret_type -- str. 戻り値のタイプ。'module'`の場合、生のモジュールオブジェクトを返します。'tkmodule'`の場合、`tkModule`オブジェクトを返します。

• is_print -- bool. ロード失敗時のエラーメッセージを表示するかどうか。

戻り値:

module or tkModule or str or None. ret_type`に応じたロードされたモジュールオブジェクト、`tkModule`オブジェクト、モジュール名、 またはエラー時に`None。

load_modules(plugin_dir='', fmask='*.py', target='read_data', ret_type='module', sort=False, is_print=True)

概要: 指定されたディレクトリから複数のプラグインモジュールをロードする。

詳細説明:

`plugin_dir`内で`fmask`に一致するファイルを検索し、それぞれのファイルをPythonモジュールとして動的にロードします。 ロードされたモジュールは`self.modules`リストに追加され、モジュール名とモジュールオブジェクトのリストを返します。 ロードに成功したモジュールは「loaded」と表示され、失敗した場合は警告が表示されます。

パラメータ:

• plugin_dir -- str. プラグインモジュールが配置されているディレクトリ。

• fmask -- str. プラグインファイルを検索するためのファイルマスク（例: '*.py'）。

• target -- str. ロードされるモジュールが対象とする機能。

• ret_type -- str. 戻り値のタイプ。'module'`の場合、生のモジュールオブジェクトを返します。'tkmodule'`の場合、`tkModule`オブジェクトを返します。

• sort -- bool. ロードするモジュールリストをファイル名の昇順でソートするかどうか。

• is_print -- bool. 処理メッセージや警告メッセージを表示するかどうか。

戻り値:

tuple[list[str], list[module | tkModule]]. (ロードされたモジュール名のリスト, ロードされたモジュールオブジェクトまたは`tkModule`オブジェクトのリスト)。

make_config_files(arg_config_file=None, fit_config_file=None)

概要: 引数定義ファイルとフィッティング変数定義ファイルのサンプルを作成する。

詳細説明:

アプリケーションの引数（`add_argument`で定義されたもの）と、 フィッティングに関連する変数（`tkParams`オブジェクトに設定されたもの）の構造を Excelファイルとして出力します。 これは、ユーザーがアプリケーションの設定を容易に行えるようにするためのテンプレートファイル生成機能です。 ファイルパスが指定されない場合、スクリプト名に基づいたデフォルトパスが使用されます。

パラメータ:

• arg_config_file -- str. 引数定義の出力ファイルパス。`None`の場合、`{filebody}_arg_config.xlsx`が使用されます。

• fit_config_file -- str. フィッティング変数定義の出力ファイルパス。`None`の場合、`{filebody}_fit_config.xlsx`が使用されます。

戻り値:

bool. ファイルの作成が成功した場合は`True`。

nohup(flag)

概要: プロセスが親シェルから独立して実行されるようにSIGHUPシグナルを無視する設定を行う。

詳細説明:

Unix系OSにおいて、`nohup`コマンドと同様の効果をプログラム内で実現します。 これにより、シェルが閉じられてもプロセスは終了しなくなります。 `signal`モジュールがインポートされている必要があります。

パラメータ:

flag -- bool. `True`の場合、SIGHUPシグナルを無視する設定を行います。

戻り値:

None.

p(str, defval=None, phrases=None)

概要: 指定された文字列に対応する多言語リソースを取得する。

詳細説明:

self.phrases`辞書（または指定された`phrases）から、 指定されたキー（str）と現在の設定言語（self.config.lang）に対応する 翻訳済みテキストを取得します。 翻訳が見つからない場合や、指定された言語のリソースがない場合は、 デフォルト値（defval）または元の文字列を返します。

パラメータ:

• str -- str. 取得したいリソースのキー文字列。

• defval -- any or None. リソースが見つからなかった場合のデフォルト値。

• phrases -- dict or None. 検索対象のリソース辞書。`None`の場合、`self.phrases`が使用されます。

戻り値:

str. 翻訳されたテキスト、デフォルト値、または元の文字列。

print(*args, **kwargs)

概要: Pythonの組み込み`print`関数を呼び出す。

詳細説明:

このメソッドは、`builtins.print`をオーバーライドしている可能性がある `self.print_redirect`とは異なり、明示的にPythonの組み込み`print`関数を呼び出します。 これにより、出力リダイレクトの影響を受けずに直接コンソールに出力できます。

パラメータ:

• args -- tuple. `print`関数に渡される位置引数。

• kwargs -- dict. `print`関数に渡されるキーワード引数。

戻り値:

None.

print_attributes(print_header=1)

概要: オブジェクトの属性とその値を標準出力に表示する。

詳細説明:

インスタンスの`__dict__`を走査し、すべての属性名とその現在値を標準出力にリストアップします。 これは、デバッグやオブジェクトの状態確認に非常に役立ちます。

パラメータ:

print_header -- int. ヘッダーメッセージ（"attributes in [ClassPath]"）を表示するかどうか。1の場合、表示されます。

戻り値:

None.

print_attributes_warning(print_header=1)

概要: オブジェクトの属性とその値を警告メッセージとして出力する。

詳細説明:

`print_attributes`と同様にオブジェクトの属性を表示しますが、 `self.print_warning`メソッドを使用するため、 出力リダイレクトが設定されている場合でもコンソールに強制的に出力されます。

パラメータ:

print_header -- int. ヘッダーメッセージ（"attributes in [ClassPath]"）を表示するかどうか。1の場合、表示されます。

戻り値:

None.

print_dict(d, header=None)

概要: 辞書の内容を標準出力に整形して表示する。

詳細説明:

指定された辞書`d`のすべてのキーと値のペアを、オプションのヘッダーとともに標準出力にリストアップします。 辞書が`None`の場合、「Null dict」と表示されます。

パラメータ:

• d -- dict or None. 表示する辞書。

• header -- str or None. 辞書の内容の前に表示するヘッダー文字列。

戻り値:

None.

print_dict_warning(d, header=None)

概要: 辞書の内容を警告メッセージとして出力する。

詳細説明:

`print_dict`と同様に辞書の内容を表示しますが、 `self.print_warning`メソッドを使用するため、 出力リダイレクトが設定されている場合でもコンソールに強制的に出力されます。 辞書が`None`の場合、「Null dict」と表示されます。

パラメータ:

• d -- dict or None. 表示する辞書。

• header -- str or None. 辞書の内容の前に表示するヘッダー文字列。

戻り値:

None.

print_parameters(params=None)

概要: アプリケーションのパラメータを標準出力に表示する。

詳細説明:

self.get_params()`（または指定された`params）に格納されているすべてのパラメータを、 キーと値のペアとして整形して標準出力にリストアップします。 値の型（float, int, strなど）に応じて適切な形式で表示されます。

パラメータ:

params -- tkParams or dict or None. 表示するパラメータオブジェクトまたは辞書。`None`の場合、`self.get_params()`が使用されます。

戻り値:

None.

print_redict(*args, **kwargs)

概要: `print_redirect`メソッドのエイリアス。

詳細説明:

`print_redirect`メソッドと同じ機能を提供します。 後方互換性または異なる命名規則のために存在する可能性があります。

パラメータ:

• args -- tuple. `print`関数に渡される位置引数。

• kwargs -- dict. `print`関数に渡されるキーワード引数。`console_out`などのリダイレクト制御パラメータを含む場合があります。

戻り値:

print_redirectメソッドの戻り値。

print_redirect(*args, **kwargs)

概要: 標準の`print`関数をオーバーライドし、指定された出力先にメッセージをリダイレクトする。

詳細説明:

builtins.print`をこのメソッドに置き換えることで、すべての`print`出力を複数のファイルやストリームに送信できるようになります。 `console_out=True`がキーワード引数に含まれる場合、元の`print`関数も使用してコンソールにメッセージを出力します。 出力がファイルの場合、カラーエスケープシーケンス（`[...]）を自動的に除去する機能もサポートします。

param args:

tuple. `print`関数に渡される位置引数。

param kwargs:

dict. print`関数に渡されるキーワード引数。 `console_out: bool. True`の場合、メッセージは元の`print`関数を使ってコンソールにも出力されます。 `end: str. 出力の最後に付加する文字列。デフォルトは改行（`

`）です。

returns:

None.

print_time(label=None, label2=None)

概要: 現在時刻を記録し、必要に応じて経過時間を出力する。

詳細説明:

self.time_stamps`辞書に指定されたラベルで現在時刻（`time.perf_counter()`と`datetime.now()）を記録します。 `label2`が指定された場合、`label`から`label2`までの経過時間も計算して表示します。 これにより、アプリケーションの各フェーズにおけるパフォーマンスを追跡できます。

パラメータ:

• label -- str or None. タイムスタンプに割り当てるラベル。`None`の場合、新しいタイムスタンプは記録されません。

• label2 -- str or None. 経過時間を計算するための終了時点のラベル。`None`の場合、経過時間は計算されません。

戻り値:

None.

print_title(message)

概要: メッセージを整形してタイトルとして表示する。

詳細説明:

指定されたメッセージの上下に区切り線（#===========...）を追加し、 アプリケーションのセクションタイトルや重要な通知として目立つように標準出力に出力します。

パラメータ:

• app -- tkApplication. アプリケーションインスタンス。

• message -- str. 表示するタイトルメッセージ。

戻り値:

None.

print_warning(*args, **kwargs)

概要: 警告メッセージを標準出力とリダイレクト先に表示する。

詳細説明:

`print_redirect`メソッドを`console_out=True`の状態で呼び出すことにより、 出力リダイレクトが設定されている場合でもコンソールに警告メッセージを強制的に出力します。 これにより、重要な警告がログファイルだけでなく、ユーザーの目にも届くようになります。

パラメータ:

• args -- tuple. `print`関数に渡される位置引数。

• kwargs -- dict. `print`関数に渡されるキーワード引数。

戻り値:

print_redirectメソッドの戻り値。

raise_error(desc='custom error')

概要: カスタムエラーを発生させる。

詳細説明:

指定された説明を持つ`CustomError`例外を発生させます。 これは、特定のアプリケーション固有の条件下でプログラムの実行を中断するために使用できます。

パラメータ:

desc -- str. エラーの説明文字列。

戻り値:

None. (例外を発生させるため、通常の戻り値はありません)。

例外:

CustomError -- 指定された説明と共にカスタムエラーを発生させます。

read_app_config(path=None, print_level=0)

概要: アプリケーションの設定ファイルを読み込む。

詳細説明:

指定されたパス、またはデフォルトのパスからアプリケーションの設定（self.config）を読み込みます。 `tkParams`オブジェクトが使用され、ファイルの内容が設定パラメータとして格納されます。 ファイルが存在しない場合でも、エラーは発生しませんが、設定は更新されません。

パラメータ:

• path -- str. 設定ファイルパス。None`の場合、スクリプト名に基づくデフォルトパス（`{filebody}.cfg）が使用されます。

• print_level -- int. 設定ファイル読み込みに関するメッセージの表示レベル。0の場合、メッセージは表示されません。

戻り値:

tuple[str, tkParams]. (読み込まれた設定ファイルのパス, 設定パラメータオブジェクト)。

read_arg_config_from_file(path, labels=['argtype', 'var_name', 'opt', 'opt_str', 'desc', 'type', 'defval', 'optional'])

概要: ファイルから引数設定を読み込み、アプリケーションの引数定義に追加する。

詳細説明:

指定されたExcelファイルから引数の定義を読み取り、 `self.args_idx_inf`（位置引数情報）と`self.args_opt_inf`（キーワード引数情報）を更新します。 これにより、外部ファイルで定義された引数をアプリケーションが認識できるようになります。 ファイルが存在しない場合、このメソッドは`False`を返して処理を終了します。

パラメータ:

• path -- str. 引数設定が記述されたExcelファイルのパス。

• labels -- list[str]. Excelファイルのヘッダー行に対応する列名のリスト。

戻り値:

bool. ファイルの読み込みと設定の更新が成功した場合は`True`、ファイルが存在しない場合は`False`。

read_args(vars=None, check_allowed_args=False, apply_default=True, pause=True)

概要: コマンドライン引数を解析し、変数を更新する。

詳細説明:

sys.argv`からコマンドライン引数を読み込み、位置引数とキーワード引数に分類します。 `add_argument`で定義された引数情報（`self.args_opt_inf, self.args_idx_inf）に基づいて、 引数の値を変数に格納し、型変換を行います。 - 不正な引数（`check_allowed_args=True`の場合）や、不足している必須引数があった場合は、

エラーメッセージとともに`None`とエラーコードを返します。

• 引数が`--key`のように値なしで与えられた場合、値は`1`とみなされます。

パラメータ:

• vars -- tkParams or dict. 解析された引数の値を格納するオブジェクトまたは辞書。`None`の場合、新しい辞書が作成されます。

• check_allowed_args -- bool. 定義されていない引数が見つかった場合にエラーとするか。`True`の場合、未定義の引数はエラーとなります。

• apply_default -- bool. 引数が与えられていない場合に、`add_argument`で設定されたデフォルト値を適用するかどうか。

• pause -- bool. ヘルプ引数が見つかった場合に、アプリケーション終了前に一時停止するかどうか。

戻り値:

tuple[dict, list, dict] or tuple[None, int, str]. 成功した場合: (キーワード引数の辞書, 位置引数のリスト, 更新された変数辞書)。 失敗した場合: (None, エラーコード, エラーメッセージ)。

read_parameters(path, merge_params=False, AddSection=0)

概要: 指定されたパスからパラメータを読み込む。

詳細説明:

`tkIniFile`クラスを使用してINIファイルまたは類似の形式からパラメータを読み込みます。 `merge_params`が`True`の場合、読み込まれたパラメータは`self.params`にマージされます。

パラメータ:

• path -- str. 読み込むパラメータファイルのパス。

• merge_params -- bool. 読み込んだパラメータを`self.params`にマージするかどうか。

• AddSection -- int. `tkIniFile`の`ReadAll`メソッドに渡される引数で、セクションを追加するかどうかを制御します。

戻り値:

dict or None. 読み込まれたパラメータの辞書。読み込みに失敗した場合は`None`。

read_resource(path, lang, phrases=None, sep='=')

概要: リソースファイル（翻訳テキストなど）を読み込む。

詳細説明:

指定されたパスからリソースファイルを読み込み、`phrases`辞書に解析して格納します。 ファイルは`key=value`または`key:value`といった特定のセパレータで区切られた形式で 記述されていることを想定しており、指定された言語でテキストをロードします。

パラメータ:

• app -- tkApplication. アプリケーションインスタンス。

• path -- str. リソースファイルのパス。

• lang -- str. 読み込むリソースの言語コード（例: 'en', 'ja'）。

• phrases -- dict or None. 読み込んだリソースを格納する辞書。`None`の場合、新しい辞書が作成されます。

• sep -- str. キーと値を区切るセパレータ文字列（例: '=', ':'）。

戻り値:

dict. 読み込んだリソースが格納された辞書。

redict(targets=None, mode='a', redirect_traceback=True, output_traceback='stdout', display_type_traceback='colored', remove_esc_sequence='file')

概要: `redirect`メソッドのエイリアス。

詳細説明:

`redirect`メソッドと同じ機能を提供します。 後方互換性または異なる命名規則のために存在する可能性があります。

パラメータ:

• targets -- str or list[str]. 出力リダイレクト先。ファイルパス（文字列）または`'stdout'`のリスト。

• mode -- str. ファイルを開くモード ('a'は追記、'w'は上書き)。

• redirect_traceback -- bool. 例外発生時のトレースバックをリダイレクトするかどうか。

• output_traceback -- str. トレースバックのリダイレクト先（'stderr'または'stdout'）。

• display_type_traceback -- str. トレースバックの表示タイプ（'colored'または'plain'）。

• remove_esc_sequence -- str. エスケープシーケンスを除去する条件（'file'の場合、ファイル出力時に除去）。

戻り値:

redirectメソッドの戻り値。

redirect(heading=None, targets=None, mode='a', redirect_traceback=True, output_traceback='stdout', display_type_traceback='colored', remove_esc_sequence='file', pause_at_terminate=True, ignore_error=True)

概要: 標準出力と例外フックをファイルまたは指定されたストリームにリダイレクトする。

詳細説明:

`builtins.print`を`self.print_redirect`に置き換え、`sys.excepthook`を`self.redirect_exception`に設定することで、 アプリケーション全体のログ出力を制御します。これにより、実行ログをファイルに保存したり、 エラー発生時の挙動をカスタマイズしたりできます。 `targets`が`None`の場合、既存のリダイレクトをすべて解除します。

パラメータ:

• heading -- str. リダイレクト開始時に表示する見出し文字列。

• targets -- str or list[str] or None. 出力リダイレクト先。ファイルパス（文字列）または`'stdout'`のリスト。`None`の場合、既存のリダイレクトを解除します。

• mode -- str. ファイルを開くモード ('a'は追記、'w'は上書き)。

• redirect_traceback -- bool. 例外発生時のトレースバックをリダイレクトするかどうか。

• output_traceback -- str. トレースバックのリダイレクト先（'stderr'または'stdout'）。

• display_type_traceback -- str. トレースバックの表示タイプ（'colored'または'plain'）。

• remove_esc_sequence -- str. エスケープシーケンスを除去する条件（'file'の場合、ファイル出力時に除去）。

• pause_at_terminate -- bool. 例外発生時、終了前に一時停止するかどうか。

• ignore_error -- bool. ファイルオープンエラーを無視するかどうか。`True`の場合、警告を出力して続行します。`False`の場合、エラーとして処理します。

戻り値:

None.

redirect_exception(hook_func=None, output='stdout', display_type='colored', pause_at_terminate=True)

概要: システムの例外処理フックをリダイレクトする。

詳細説明:

`sys.excepthook`を`exception_hook`メソッド（または指定されたカスタムフック関数）に設定し、 未処理の例外発生時の挙動を制御します。 `pygments`ライブラリが利用可能な場合にのみ、カラー表示などの機能が有効になります。

パラメータ:

• hook_func -- callable. 使用するカスタム例外フック関数。`None`の場合、`self.exception_hook`が使用されます。

• output -- str. トレースバックの出力先 ('stderr' または 'stdout')。

• display_type -- str. トレースバックの表示形式 ('colored' または 'plain')。

• pause_at_terminate -- bool. 終了時にユーザー入力で一時停止するかどうか。

戻り値:

None.

replace_path(path=None, template=None, ext_dict={'dirname': 'D:\\git\\sphinx\\tkProg', 'ext': '.xls', 'filebody': 'xrd', 'filename': 'xrd.xls', 'fullpath': 'D:\\git\\sphinx\\tkProg\\xrd.xls'})

概要: 指定されたパスをテンプレートに基づいて新しいパスに変換する。

詳細説明:

tklib.tkutils.replace_path`関数を呼び出し、入力ファイルパスやスクリプトパスを元に、 ディレクトリ名、ファイル名本体、拡張子などの要素を組み合わせて新しいパスを生成します。 テンプレートには`{dirname}, {filebody}, `{ext}`などのプレースホルダーを使用できます。

パラメータ:

• path -- str. 変換元のパス。`None`の場合、`self.script_fullpath`が使用されます。

• template -- str or list[str]. 新しいパスを生成するためのテンプレート文字列。リストの場合、`os.path.join`で結合されます。

• ext_dict -- dict. 拡張子を置き換えるための辞書（例: {'.in': '.out'}）。

戻り値:

str. 変換された新しいパス。

save_arg_config(outfile, labels=['argtype', 'var_name', 'opt', 'opt_str', 'desc', 'type', 'defval', 'optional'])

概要: 現在の引数設定をファイルに保存する。

詳細説明:

`self.args_idx_inf`（位置引数情報）と`self.args_opt_inf`（キーワード引数情報）に 格納されている引数定義を抽出し、指定されたファイルにExcelまたはCSV形式で保存します。 これにより、アプリケーションの引数設定をテンプレートとして出力したり、バックアップしたりできます。

パラメータ:

• outfile -- str. 出力ファイルパス。拡張子 (.csv, .xlsx) に応じてファイル形式が決定されます。

• labels -- list[str]. 保存する引数属性のラベルリスト。Excelファイルのヘッダー行に対応します。

戻り値:

None.

save_parameters(path, params=None, section='Parameters', otherparams=None)

概要: アプリケーションのパラメータをファイルに保存する。

詳細説明:

tkIniFile`クラスを使用して、`self.params`（または指定された`params）と `otherparams`に格納されているパラメータを指定されたファイルにINI形式で書き出します。 メインパラメータは指定された`section`に、`otherparams`は'Preferences'セクションに保存されます。

パラメータ:

• path -- str. 保存先のファイルパス。

• params -- tkParams or dict or None. 保存するメインのパラメータオブジェクトまたは辞書。`None`の場合、`self.get_params()`が使用されます。

• section -- str. メインパラメータが保存されるセクション名。

• otherparams -- dict or None. 追加で保存するパラメータの辞書。これらは'Preferences'セクションに保存されます。

戻り値:

None.

set_exception(func=None, print_level=1)

概要: グローバルな例外処理フックを設定する。

詳細説明:

`tklib.tkutils.set_exception`関数を呼び出し、未処理の例外が発生した場合の グローバルなハンドラを設定します。これにより、例外発生時の動作をカスタマイズできます。 `func`が`None`の場合、デフォルトの例外ハンドラが設定されます。

パラメータ:

• func -- callable. 例外ハンドラとして設定する関数。`None`の場合、デフォルトのハンドラが設定されます。

• print_level -- int. 例外情報の出力レベル。

戻り値:

None.

set_usage(usage_str='', suppress_usage='')

概要: アプリケーションの用法説明を設定する。

詳細説明:

アプリケーションの起動時（または`usage`メソッドが呼び出された時）に表示される 用法説明文字列と、その表示を抑制する設定を更新します。

パラメータ:

• usage_str -- str. アプリケーションの用法説明として使用する文字列。

• suppress_usage -- str. 用法説明の表示を抑制するためのキーワード（例: 'all', 'usage', 'options'）。

戻り値:

None.

terminate(message=None, post_message=None, input_text='Press ENTER to terminate>>\n', usage=None, pause=False)

概要: アプリケーションを終了し、必要に応じてメッセージや用法説明を表示する。

詳細説明:

アプリケーションの実行を停止し、終了コード0でプロセスを終了します。 終了前に、指定されたメッセージ、用法説明、および追加のメッセージを表示できます。 また、`pause`が`True`の場合、終了前にユーザー入力で一時停止するオプションも提供します。 `save_time`が有効な場合、終了時の時刻と起動からの経過時間も表示します。

パラメータ:

• message -- str or None. 終了時に表示するメッセージ。

• post_message -- str or None. メッセージの後に表示する追加メッセージ。

• input_text -- str. 一時停止時にユーザーに表示するプロンプト文字列。

• usage -- str or callable or None. 表示する用法説明。`'built-in'`またはカスタム関数を指定できます。

• pause -- bool. 終了前にユーザー入力で一時停止するかどうか。

戻り値:

None. (アプリケーションは終了するため、通常の戻り値はありません)。

update_vars(vars=None, usage=None, check_allowed_args=True, apply_default=True)

概要: コマンドライン引数を解析し、指定された変数オブジェクトを更新する。

詳細説明:

`read_args`メソッドを呼び出してコマンドライン引数を解析し、結果を指定された`vars`オブジェクトに適用します。 引数解析中にエラーが発生した場合、エラーメッセージと用法説明を表示してアプリケーションを終了します。 これにより、アプリケーションの起動時に必要な引数が正しく渡されたことを確認できます。

パラメータ:

• vars -- tkParams or dict. 更新する変数オブジェクト。`None`の場合、`self.cparams`が使用されます。

• usage -- callable or str or None. 用法説明を表示するための関数または`'built-in'`。`None`の場合、`self.usage`が使用されます。

• check_allowed_args -- bool. 定義されていない引数をチェックするかどうか。`True`の場合、未定義の引数はエラーとなります。

• apply_default -- bool. デフォルト値を適用するかどうか。`True`の場合、引数が与えられていない変数にデフォルト値が設定されます。

戻り値:

tuple[dict, list, dict]. (キーワード引数の辞書, 位置引数のリスト, 更新された変数辞書)。

usage(*args)

概要: アプリケーションの用法説明を表示する。

詳細説明:

`self.usage_str`に設定されたカスタム用法説明、または`add_argument`で定義された 引数情報に基づいて、アプリケーションの使用方法とオプションのリストを標準出力に表示します。 `self.suppress_usage`設定により表示を制御できます。 カスタム`usage_str`には`{var}`形式のプレースホルダーを含めることができ、 `self.args_vars`の値で置換されます。

パラメータ:

args -- tuple. 将来的な拡張のための追加引数（現在未使用）。

戻り値:

None.

write_resource(path, mode)

概要: リソースファイル（翻訳テキストなど）を書き込む。

詳細説明:

`app.phrases`辞書に格納されているリソース（多言語対応のテキストなど）を、 指定されたパスにファイルとして書き出します。 各キーに対応する指定された言語の値を`key:val`形式で保存します。

パラメータ:

• app -- tkApplication. アプリケーションインスタンス。

• path -- str. 出力ファイルパス。

• mode -- str. ファイルを開くモード（例: 'w'）。

戻り値:

bool. 書き込みが成功した場合は`True`。