tkapplication.py 技術ドキュメント

ライブラリの機能や目的

tkapplication.py は、Pythonアプリケーション開発のための強力な基盤クラス tkApplication を提供するライブラリです。このライブラリの主な目的は、アプリケーション開発において共通的に必要となる様々なユーティリティ機能（コマンドライン引数の解析、設定ファイルの管理、時間計測、出力リダイレクト、エラーハンドリング、プラグインモジュールのロードと呼び出しなど）を集約し、開発者がビジネスロジックに集中できるようにすることです。

主な機能:

  • コマンドライン引数解析: アプリケーションのコマンドライン引数を効率的に定義し、解析します。位置引数とキーワード引数の両方に対応し、型変換やデフォルト値の設定も可能です。

  • 設定ファイル管理: アプリケーション固有の設定ファイル（INI形式やExcel形式）の読み書きをサポートし、設定を簡単に管理できます。

  • 出力リダイレクト: 標準出力や標準エラー出力に加え、ファイルへの出力を簡単にリダイレクトできます。複数の出力先への同時出力も可能です。

  • エラーハンドリングとトレースバックの整形: 例外発生時のトレースバックを色付けして表示したり、リダイレクトされた出力先に書き出したりする機能を提供します。

  • プラグインモジュール管理: 指定されたディレクトリからPythonモジュールを動的にロードし、その中の関数を呼び出すプラグイン機構をサポートします。

  • 時間計測: アプリケーションの各段階におけるタイムスタンプを記録し、経過時間を計算・表示する機能を提供します。

  • 多言語対応: フレーズ管理機能を通じて、アプリケーションのメッセージの多言語対応をサポートします。

  • アプリケーションパスと環境情報: スクリプトの実行パス、ユーザー名、OS名など、アプリケーションの実行環境に関する情報を取得・管理します。

このライブラリは、特にコマンドラインツールやGUIアプリケーションのバックエンドとして、共通のロジックやインフラストラクチャを再利用可能な形で提供し、開発効率の向上とコードの一貫性を目指しています。

importする方法

このライブラリを他のPythonプログラムからimportするには、以下のいずれかの方法を使用します。

tkApplication クラスを直接importする場合:

from tkapplication import tkApplication

ライブラリ全体をimportし、tkApplication クラスを参照する場合:

import tkapplication

app = tkapplication.tkApplication()

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

tkapplication.py は、いくつかの非標準ライブラリと、別途提供される tklib パッケージに依存しています。

非標準ライブラリ:

  • pygments: 例外発生時のトレースバックを色付けして整形するために使用されます。

  • openpyxl: Excelファイル（.xlsx）形式の引数定義ファイルやフィッティング設定ファイルを読み書きするために使用されます。

  • getpass: 現在のシステムユーザー名を取得するために使用されます。これはPythonの標準ライブラリですが、ここでは非標準ライブラリとして記載します。

依存する tklib パッケージ: tkapplication.py は、以下の tklib パッケージ内のモジュールに深く依存しています。 tklib.tkobject, tklib.tkparams, tklib.tkvariousdata, tklib.tkfile, tklib.tkplugin, tklib.tkutils

インストール方法:

これらの非標準ライブラリは、pip コマンドを使用してインストールできます。

pip install pygments openpyxl

tklib パッケージについては、PyPIに登録されている場合は同様に pip install tklib でインストールできます。もしPyPIにない場合は、tklib のソースコードを tkapplication.py と同じディレクトリ構造（tklib ディレクトリを配置する）で配置するか、Pythonの sys.path に tklib の親ディレクトリを追加する必要があります。

importできる変数と関数

関数

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

フィッティング設定をCSVまたはXLSXファイルとして保存します。

  • 動作: vars オブジェクトから指定された labels に従ってデータを抽出し、outfile にCSVまたはXLSX形式で保存します。outfile の拡張子によってフォーマットが自動的に選択されます。

  • 引数:

    • vars: 設定情報を持つオブジェクト。通常は tkParams のインスタンスのように、属性として設定値を持つことを想定しています。print_variables() メソッドを持つ場合、それが呼び出されます。

    • outfile: 保存先のファイルパス。.csv または .xlsx 拡張子を持つ必要があります。

    • labels (オプション): vars オブジェクトから抽出する属性名のリスト。デフォルトはフィッティング変数に関連するラベルです。

    • section (オプション): 現在未使用。将来的な拡張用と思われます。

  • 戻り値: 保存が成功した場合は保存結果（tkVariousData().save の戻り値）、失敗した場合は None。

main()

このライブラリがメインスクリプトとして実行されたときに呼び出される関数です。

  • 動作: このファイルがライブラリであり、直接実行するものではないことを示すメッセージを標準出力に表示します。

  • 引数: なし。

  • 戻り値: なし。

変数

use_colored_traceback

pygments ライブラリがシステムにインストールされ、正しくimportできたかどうかを示すブール型のフラグです。

  • 説明: True の場合、tkApplication クラスの例外フックが色付きのトレースバックを出力しようとします。False の場合、通常のプレーンテキストのトレースバックが出力されます。

クラス

class tkApplication(tkObject)

アプリケーションの基盤となるクラスで、tklib.tkobject.tkObject を継承しています。コマンドライン引数の解析、設定管理、出力制御、プラグイン機能など、アプリケーション開発に共通する多くのユーティリティを提供します。

__init__(self, usage_str = "", suppress_usage = '', _globals = None, locals = None, use_user_inifile = False, inifile_dirs = ['ini'], create_inidir = False, save_time = True, **args)

tkApplication クラスのコンストラクタです。アプリケーションの初期設定、パスの解析、引数管理オブジェクトの初期化などを行います。

  • 動作:

    • 親クラス tkObject のコンストラクタを呼び出します。

    • OS名、コマンドライン引数（sys.argv）、スクリプトのパス情報を取得・保存します。

    • 設定ファイル（INIファイル）のディレクトリとパスを決定します。

    • 標準の print 関数を self.print_original に保存し、出力リダイレクトに備えます。

    • tkParams オブジェクトとしてアプリケーション設定 (self.config) とアプリケーショングローバル変数 (self.params)、スクリプト変数 (self.svars) を初期化します。

    • タイムスタンプの記録設定 (save_time) を行い、起動時刻を記録します。

    • ユーザー名を取得します。

    • 渡された args を使って属性を更新します。

  • 引数:

    • usage_str (オプション): usage() メソッドで表示される使用方法の文字列。

    • suppress_usage (オプション): usage() メソッドで抑制する項目（例: 'all', 'usage', 'options'）。

    • _globals (オプション): アプリケーションのグローバル変数を参照するための辞書（通常は globals() を渡す）。

    • locals (オプション): アプリケーションのローカル変数を参照するための辞書（通常は locals() を渡す）。

    • use_user_inifile (オプション): ユーザー固有の設定ファイル (_username.ini) を使用するかどうか。

    • inifile_dirs (オプション): 設定ファイルを検索するディレクトリのリスト。

    • create_inidir (オプション): 設定ファイルディレクトリが存在しない場合に作成するかどうか。

    • save_time (オプション): アプリケーションの実行時間を記録するかどうか。

    • **args: その他のキーワード引数で、tkApplication インスタンスの属性として直接設定されます。

  • 戻り値: なし。

__del__(self)

tkApplication オブジェクトが破棄されるときに呼び出されるデストラクタです。

  • 動作: リダイレクトされた出力ストリーム（ファイルオブジェクト）が存在する場合、それらを閉じます。

  • 引数: なし。

  • 戻り値: なし。

__str__(self)

オブジェクトの文字列表現を返します。

  • 動作: self.ClassPath() メソッドによってクラスの完全修飾名を返します。

  • 引数: なし。

  • 戻り値: クラスパスを示す文字列。

nohup(self, flag)

SIGHUPシグナルを無視するように設定します（POSIXシステムのみ）。

  • 動作: flag が True の場合、signal.SIGHUP を signal.SIG_IGN に設定し、端末からの切断時にプロセスが終了しないようにします。

  • 引数:

    • flag (bool): SIGHUPを無視するかどうか。

  • 戻り値: なし。

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

プロセスをデーモン化します（POSIXシステムのみ）。

  • 動作: プロセスをバックグラウンドで実行されるデーモンとして設定します。標準入出力およびエラー出力を指定されたパスにリダイレクトし、親プロセスから分離します。

  • 引数:

    • stdin_path (オプション): 標準入力をリダイレクトするファイルパス。

    • stdout_path (オプション): 標準出力をリダイレクトするファイルパス。

    • stderr_path (オプション): 標準エラー出力をリダイレクトするファイルパス。

    • print_level (オプション): デーモン化の情報を出力するかどうか。

  • 戻り値: なし。

  • 注意: WindowsなどPOSIX以外のOSで呼び出された場合、エラーメッセージを表示して terminate() します。

raise_error(self, desc = "custom error")

カスタムエラーを発生させます。

  • 動作: CustomError というカスタム例外クラスを定義し、指定された説明文でその例外を発生させます。

  • 引数:

    • desc (オプション): エラーの説明文字列。

  • 戻り値: なし（例外を発生させる）。

set_exception(self, func = None, print_level = 1)

例外フックを設定します。

  • 動作: tklib.tkutils.set_exception 関数を呼び出し、グローバルな例外ハンドラを設定します。

  • 引数:

    • func (オプション): 例外発生時に呼び出される関数。None の場合はデフォルトの例外ハンドラが使用されます。

    • print_level (オプション): 診断情報の出力レベル。

  • 戻り値: なし。

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

例外発生時に sys.excepthook から呼び出されるハンドラ関数です。

  • 動作: トレースバック情報を取得し、pygments が利用可能な場合は色付けして整形し、指定された出力先に書き出します。終了時に一時停止するかどうかも制御します。

  • 引数:

    • type: 例外の型。

    • value: 例外オブジェクト。

    • tb: トレースバックオブジェクト。

    • output (オプション): トレースバックの出力先 ('stderr' または 'stdout')。

    • display_type (オプション): トレースバックの表示形式 ('colored' または 'plain')。

    • pause_at_terminate (オプション): 終了時にユーザー入力を待つかどうか。

  • 戻り値: なし。

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

sys.excepthook をカスタムの例外ハンドラに設定し、例外出力をリダイレクトします。

  • 動作: sys.excepthook を exception_hook メソッド、または指定された hook_func に設定します。これにより、未処理の例外が発生した場合の動作をカスタマイズできます。

  • 引数:

    • hook_func (オプション): 使用するカスタム例外フック関数。None の場合は self.exception_hook が使用されます。

    • output (オプション): exception_hook に渡す出力先。

    • display_type (オプション): exception_hook に渡す表示形式。

    • pause_at_terminate (オプション): exception_hook に渡す終了時一時停止フラグ。

  • 戻り値: なし。

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

redirect メソッドのエイリアスです。

redirect(self, 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)

アプリケーションの出力ストリームと例外ハンドリングをリダイレクトします。

  • 動作:

    • 組み込みの print() 関数を self.print_redirect に置き換えます。

    • targets に指定されたファイルパスを開き、出力先として登録します。'stdout' を指定すると標準出力にも出力されます。

    • redirect_traceback が True の場合、sys.excepthook をカスタムハンドラ (self.exception_hook) に設定し、例外トレースバックの出力もリダイレクトします。

    • 既存のリダイレクトをクリアするには targets = None を指定します。

  • 引数:

    • heading (オプション): リダイレクト開始時に表示する見出し文字列。

    • targets (オプション): 出力先のファイルパス（文字列またはリスト）。None の場合、既存のリダイレクトを解除します。

    • mode (オプション): ファイルオープンモード（例: 'a' は追記、'w' は上書き）。

    • redirect_traceback (オプション): 例外トレースバックもリダイレクトするかどうか。

    • output_traceback (オプション): 例外トレースバックの出力先 ('stdout' または 'stderr')。

    • display_type_traceback (オプション): 例外トレースバックの表示形式 ('colored' または 'plain')。

    • remove_esc_sequence (オプション): エスケープシーケンス（色情報など）をファイル出力から除去するかどうか ('file' を指定するとファイル出力時のみ除去)。

    • pause_at_terminate (オプション): 例外終了時に一時停止するかどうか。

    • ignore_error (オプション): ファイルオープンエラーを無視するかどうか。False の場合、エラー時に終了します。

  • 戻り値: なし。

replace_path(self, path = None, template = None, ext_dict = {})

ファイルパスのテンプレート置換を行います。

  • 動作: 指定された path の情報を基に、template 文字列内の {dirname}, {basename}, {filebody}, {ext} などのプレースホルダを実際の値に置換して新しいパスを生成します。

  • 引数:

    • path (オプション): 元となるファイルパス。None の場合、self.script_fullpath が使用されます。

    • template (オプション): 新しいパスの生成に使うテンプレート文字列。リスト形式で渡すと os.path.join で結合されます。

    • ext_dict (オプション): 拡張子置換用の辞書。

  • 戻り値: 置換された新しいパス文字列。

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

設定ファイル（INIファイル）を格納するディレクトリのパスを取得します。

  • 動作: use_user_inifile が False の場合、スクリプトと同じディレクトリを返します。True の場合、inifile_dirs で指定されたディレクトリをスクリプトディレクトリのサブディレクトリとして検索し、存在すればそれを返します。create_inidir が True であれば、存在しないディレクトリも作成対象とします。

  • 引数:

    • use_user_inifile (オプション): ユーザー固有の設定ファイルディレクトリを使用するかどうか。

    • inifile_dirs (オプション): 設定ファイルを検索するサブディレクトリ名のリスト。

    • create_inidir (オプション): ディレクトリが存在しない場合に作成するかどうか。

    • defval (オプション): 有効なディレクトリが見つからなかった場合のデフォルト値。

  • 戻り値: 設定ファイルディレクトリのパス文字列。

get_inifile_path(self, inidir, use_user_inifile = False)

設定ファイル（INIファイル）のフルパスを取得します。

  • 動作: 指定された inidir とスクリプトのファイル本体名に基づいて、設定ファイルのパスを生成します。use_user_inifile が True の場合、ユーザー名を含むファイル名 (_username.ini) を使用します。

  • 引数:

    • inidir: 設定ファイルディレクトリのパス。

    • use_user_inifile (オプション): ユーザー固有の設定ファイルを使用するかどうか。

  • 戻り値: 設定ファイルのフルパス文字列。

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

入力ファイルと設定ファイルのパスを解析し、それぞれの役割を決定します。

  • 動作: path が config_ext で指定された設定ファイルの拡張子を持つ場合、path を設定ファイルとみなし、入力ファイルはそこから読み込まれると仮定します。そうでない場合、path を入力ファイルとみなし、設定ファイルのパスは入力ファイルのパスから派生させます。

  • 引数:

    • app: tkApplication のインスタンス。

    • path: 解析対象のファイルパス。

    • infile_ext (オプション): 入力ファイルとして認識する拡張子のリスト（現在未使用）。

    • config_ext (オプション): 設定ファイルとして認識する拡張子のリスト。

    • print_level (オプション): 診断情報の出力レベル。

  • 戻り値: (infile, config_path, infile_stored) のタプル。

    • infile: 決定された入力ファイルのパス（path が設定ファイルだった場合は None）。

    • config_path: 決定された設定ファイルのパス。

    • infile_stored: infile と同じ（infile が設定ファイルだった場合は None）。

read_app_config(self, path = None, print_level = 0)

アプリケーション設定ファイルを読み込みます。

  • 動作: tkParams オブジェクトである self.config を使用して、指定された path からパラメータを読み込みます。path が None の場合、デフォルトの設定ファイルパスが使用されます。

  • 引数:

    • path (オプション): 読み込む設定ファイルのパス。

    • print_level (オプション): 診断情報の出力レベル。

  • 戻り値: (appconfig_path, config) のタプル。

    • appconfig_path: 実際に読み込まれた設定ファイルのパス。

    • config: tkParams オブジェクトに読み込まれた設定。

get_args(self)

コマンドライン引数を取得します。

  • 動作: sys.argv とその長さを返します。

  • 引数: なし。

  • 戻り値: (argv, len(argv)) のタプル。

get_argv(self)

コマンドライン引数を取得します（get_args と同じ）。

  • 動作: sys.argv とその長さを返します。

  • 引数: なし。

  • 戻り値: (sys.argv, len(sys.argv)) のタプル。

get_params(self)

アプリケーションのパラメータを格納する tkParams オブジェクトを返します。

  • 動作: self.params オブジェクトを返します。

  • 引数: なし。

  • 戻り値: tkParams オブジェクト。

get_param_dict(self)

アプリケーションのパラメータを辞書形式で返します。

  • 動作: self.params オブジェクトの get_param_dict() メソッドを呼び出します。

  • 引数: なし。

  • 戻り値: パラメータを格納した辞書。

get_param_dic(self)

アプリケーションのパラメータを辞書形式で返します。

  • 動作: self.params オブジェクトの __dict__ 属性を返します。

  • 引数: なし。

  • 戻り値: パラメータを格納した辞書。

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

コマンドライン引数から指定された引数の値を取得します。

  • 動作: sys.argv を走査し、varname に対応する引数の値を見つけます。varname が整数の場合、位置引数として扱います。キーワード引数の場合、= の右側の値を抽出し、vartype に従って型変換します。

  • 引数:

    • varname: 取得する引数の名前（文字列）または位置（整数）。

    • defval (オプション): 引数が見つからなかった場合のデフォルト値。

    • vartype (オプション): 引数の値を変換する型（例: 'str', 'int', 'float'）。

  • 戻り値: 変換された引数の値、または defval。

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

コマンドライン引数の存在をチェックし、その値を取得します。

  • 動作: sys.argv を走査し、varname に対応する引数の値を見つけます。定義済みの引数情報 self.args_opt_inf を利用して、デフォルト値や型情報を補完します。

  • 引数:

    • varname: 取得する引数の名前（文字列）または位置（整数）。

    • defval (オプション): 引数が見つからなかった場合のデフォルト値。

    • vartype (オプション): 引数の値を変換する型。

  • 戻り値: 変換された引数の値、または defval。

make_config_files(self, arg_config_file = None, fit_config_file = None)

引数定義ファイルとフィッティング変数定義ファイルのサンプルを生成します。

  • 動作: ハードコードされたサンプルデータを使用して、コマンドライン引数の定義をExcelファイル (_arg_config.xlsx) に、フィッティング変数定義をExcelファイル (_fit_config.xlsx) に保存します。これは、アプリケーションが受け入れる引数のテンプレートとして利用できます。

  • 引数:

    • arg_config_file (オプション): 引数定義ファイルの出力パス。None の場合、スクリプト名から派生します。

    • fit_config_file (オプション): フィッティング変数定義ファイルの出力パス。None の場合、スクリプト名から派生します。

  • 戻り値: 常に True。

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

引数定義ファイルを読み込み、アプリケーションに引数を登録します。

  • 動作: 指定されたExcelファイル (.xlsx) から引数定義を読み込み、self.args_idx_inf (位置引数情報) と self.args_opt_inf (キーワード引数情報) に格納します。

  • 引数:

    • path: 読み込むExcelファイルパス。

    • labels (オプション): Excelファイルのヘッダ行に対応するカラム名のリスト。

  • 戻り値: 読み込みが成功した場合は True、ファイルが存在しない場合は False。

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

現在の引数定義をファイルに保存します。

  • 動作: self.args_idx_inf と self.args_opt_inf に格納されている引数定義情報を抽出し、指定された outfile にExcel形式で保存します。

  • 引数:

    • outfile: 保存先のExcelファイルパス。

    • labels (オプション): 出力するカラム名のリスト。

  • 戻り値: なし。

add_argument(self, 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() や usage() メソッドが動作します。

  • 引数:

    • opt (オプション): キーワード引数 (--name) のオプション名。None の場合、位置引数として扱われます。

    • opt_str (オプション): usage() メソッドで表示される引数の使用方法文字列。

    • var_name (オプション): 引数として解析された値が格納される変数名。

    • desc (オプション): 引数の説明。

    • type (オプション): 引数の期待されるデータ型（例: 'str', 'int', 'float', 'int|str'）。

    • defval (オプション): 引数のデフォルト値。

    • optional (オプション): 引数がオプションであるか必須であるか。

  • 戻り値: (inf_opt, inf_idx) のタプル。更新されたキーワード引数情報と位置引数情報の辞書およびリスト。

check_help(self, pause = True)

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

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

  • 引数:

    • pause (オプション): 終了時に一時停止するかどうか。

  • 戻り値: なし（見つかった場合はアプリケーションを終了）。

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

コマンドライン引数を解析し、指定された変数辞書またはオブジェクトに格納します。

  • 動作: sys.argv を解析し、定義済みの引数 (self.args_opt_inf, self.args_idx_inf) に従って、引数の値を取得し型変換を行います。結果は self.args_opt (キーワード引数)、self.args_idx (位置引数)、self.args_vars (すべての引数を格納する辞書) に格納されます。

  • 引数:

    • vars (オプション): 解析された引数を格納する変数辞書またはオブジェクト。None の場合、新しい辞書が作成されます。

    • check_allowed_args (オプション): 未定義の引数が存在する場合にエラーとするかどうか。

    • apply_default (オプション): 引数が与えられなかった場合にデフォルト値を適用するかどうか。

    • pause (オプション): エラー発生時に終了時に一時停止するかどうか。

  • 戻り値: 成功した場合 (args_opt, args_idx, args_vars) のタプル。エラーが発生した場合は (None, エラーコード, エラーメッセージ) のタプル。

force_given_args(self, cparams)

解析されたコマンドライン引数を、指定されたパラメータオブジェクトの属性に強制的に設定します。

  • 動作: read_args() で解析された self.args_idx と self.given_args の内容を、引数 cparams の属性として上書き設定します。これにより、コマンドラインで指定された値が優先的に適用されます。

  • 引数:

    • cparams: 引数を設定するターゲットとなるオブジェクト（通常は tkParams のインスタンスなど）。

  • 戻り値: なし。

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

コマンドライン引数を解析し、変数を更新します。エラー発生時には適切なメッセージを表示してアプリケーションを終了します。

  • 動作: read_args() を呼び出して引数を解析し、エラーが検出された場合は terminate() メソッドを使用してアプリケーションを終了します。

  • 引数:

    • vars (オプション): 引数を更新する対象の変数辞書またはオブジェクト。None の場合、self.cparams が使用されます。

    • usage (オプション): エラー時に表示する使用方法メッセージ。

    • check_allowed_args (オプション): 未定義の引数をエラーとするかどうか。

    • apply_default (オプション): デフォルト値を適用するかどうか。

  • 戻り値: 成功した場合 (args_opt, args_idx, args_vars) のタプル。エラー発生時はアプリケーションが終了するため戻り値はありません。

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

アプリケーションの使用方法メッセージを設定します。

  • 動作: usage_str に指定された文字列と、usage() メソッドで抑制する項目を self の属性に保存します。

  • 引数:

    • usage_str (オプション): 使用方法として表示する文字列。

    • suppress_usage (オプション): usage() で抑制する項目（例: 'all', 'usage', 'options'）。

  • 戻り値: なし。

usage(self, *args)

定義されたコマンドライン引数情報に基づいて、アプリケーションの使用方法（ヘルプ）を標準出力に表示します。

  • 動作: self.usage_str が設定されていればそれを表示します。そうでなければ、add_argument() で登録されたキーワード引数と位置引数の情報（オプション名、デフォルト値、型、説明）を整形して表示します。suppress_usage 設定に応じて一部の表示を抑制できます。

  • 引数: 任意の引数（現在未使用）。

  • 戻り値: なし。

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

アプリケーションを終了します。

  • 動作: アプリケーションを終了する前に、指定されたメッセージ、使用方法、後続メッセージを表示し、オプションでユーザー入力を待機します。save_time が有効な場合は、起動からの経過時間も表示します。

  • 引数:

    • message (オプション): 終了前に表示するメッセージ。

    • post_message (オプション): メッセージと使用方法の後に表示するメッセージ。

    • input_text (オプション): 一時停止時に表示するプロンプト文字列。

    • usage (オプション): 使用方法を表示する場合、'built-in' または tkApplication インスタンスを引数として受け取る関数を指定します。

    • pause (オプション): 終了時にユーザー入力を待つかどうか。

  • 戻り値: なし（exit() を呼び出すため、プログラムが終了します）。

write_resource(app, path, mode)

リソースファイル（多言語フレーズなど）を書き込むメソッドです。

  • 動作: app.phrases 辞書の内容を、指定されたパスにリソースファイルとして書き出します。各行は key:value の形式で、指定された言語の値を保存します。

  • 引数:

    • app: tkApplication のインスタンス。

    • path: 書き出すファイルパス。

    • mode: ファイルオープンモード（'w' など）。

  • 戻り値: 常に True。

  • 注意: コード中の f 変数は未定義であり、また lang 変数も外部から渡されないため、このメソッドは現状では機能しません。

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

リソースファイル（多言語フレーズなど）を読み込みます。

  • 動作: 指定された path のリソースファイル（例: key=value 形式のファイル）を読み込み、phrases 辞書に phrases[key][lang] = value の形式で格納します。エンコーディングは shift_jis を試行します。

  • 引数:

    • app: tkApplication のインスタンス。

    • path: 読み込むリソースファイルのパス。

    • lang: 読み込んだフレーズに割り当てる言語コード。

    • phrases (オプション): 読み込んだフレーズを格納する辞書。None の場合、新しい辞書が作成されます。

    • sep (オプション): キーと値を区切るセパレータ文字列。

  • 戻り値: 読み込んだフレーズを格納した辞書。

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

多言語対応のフレーズを取得します。

  • 動作: phrases 辞書から、指定された str に対応する現在の言語のフレーズを取得します。フレーズが見つからない場合は、defval または元の str を返します。

  • 引数:

    • str: 検索するフレーズのキー。

    • defval (オプション): フレーズが見つからなかった場合のデフォルト値。

    • phrases (オプション): フレーズを検索する辞書。None の場合、self.phrases が使用されます。

  • 戻り値: 取得したフレーズ文字列。

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

指定されたPythonモジュールを動的にロードします。

  • 動作: importlib.import_module を使用して module_name のモジュールをロードします。ロードされたモジュールは self.modules リストに格納され、tkModule オブジェクトとしてラップされることもあります。

  • 引数:

    • module_name: ロードするモジュールの名前。

    • target (オプション): モジュールがターゲットとする機能の識別子（例: 'read_data'）。

    • plugin_dir (オプション): モジュールが置かれているディレクトリ。sys.path に追加されます。

    • desc (オプション): モジュールの説明。

    • ret_type (オプション): 戻り値の型（'module' または 'tkmodule'）。

    • is_print (オプション): エラーメッセージを出力するかどうか。

  • 戻り値: ロードされたモジュールオブジェクト、または tkModule オブジェクト、または module_name 文字列、または None (失敗時)。

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

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

  • 動作: plugin_dir 内で fmask に一致するすべてのPythonファイルを見つけ、それぞれをプラグインモジュールとして load_module() を使ってロードします。

  • 引数:

    • plugin_dir (オプション): プラグインモジュールを検索するディレクトリ。

    • fmask (オプション): 検索するファイル名のパターン（例: '*.py'）。

    • target (オプション): ロードされたモジュールに設定するターゲット識別子。

    • ret_type (オプション): load_module() に渡す戻り値の型。

    • sort (オプション): ロードするファイルの順序をソートするかどうか。

    • is_print (オプション): ロード状況や警告メッセージを出力するかどうか。

  • 戻り値: (module_names2, modules) のタプル。

    • module_names2: 成功したロードされたモジュールの名前のリスト。

    • modules: ロードされたモジュールオブジェクトまたは tkModule オブジェクトのリスト。

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

ロードされたモジュール内の特定の関数を呼び出します。

  • 動作: self.modules リストを走査し、module_name に一致するモジュールを見つけます。そのモジュール内に func_name という関数があれば、それに *args と **kwargs を渡して呼び出します。モジュール内で見つからなければ、self.globals 内の関数を呼び出そうとします。

  • 引数:

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

    • func_name: 呼び出す関数の名前。

    • *args: 関数に渡す位置引数。

    • **kwargs: 関数に渡すキーワード引数。

  • 戻り値: 呼び出された関数の戻り値。関数が見つからない場合は terminate() を呼び出して終了します。

call_all(self, func_name, *args)

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

  • 動作: self.modules にロードされているすべてのモジュールを走査し、func_name という関数があれば、それに *args を渡して呼び出します。いずれのモジュールにも関数が見つからなければ、self.globals 内の関数を呼び出します。

  • 引数:

    • func_name: 呼び出す関数の名前。

    • *args: 関数に渡す位置引数。

  • 戻り値: 最後に呼び出された関数の戻り値。呼び出されなかった場合は None。

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

INI形式のパラメータファイルを読み込みます。

  • 動作: tkIniFile を使用して、指定された path からすべてのパラメータを読み込みます。merge_params が True の場合、読み込んだパラメータを self.params にマージします。

  • 引数:

    • path: 読み込むINIファイルのパス。

    • merge_params (オプション): 読み込んだパラメータを self.params にマージするかどうか。

    • AddSection (オプション): 読み込んだパラメータを tkParams に追加する際のセクション番号（tkIniFile の仕様に基づく）。

  • 戻り値: 読み込まれたパラメータを格納する辞書のようなオブジェクト。

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

パラメータをINIファイルに保存します。

  • 動作: params または self.get_params() からキーと値を抽出し、指定された path にINI形式で書き込みます。otherparams があれば、それも 'Preferences' セクションに書き込みます。

  • 引数:

    • path: 保存先のINIファイルパス。

    • params (オプション): 保存するパラメータを持つ辞書のようなオブジェクト。None の場合、self.get_params() が使用されます。

    • section (オプション): パラメータを保存するINIファイルのセクション名。

    • otherparams (オプション): 'Preferences' セクションに保存する追加のパラメータ。

  • 戻り値: なし。

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

tkapplication.py ファイルがPythonインタプリタによって直接実行された場合（例: python tkapplication.py）、ファイルの最下部にある以下のコードブロックが実行されます。

if __name__ == "__main__":
    main()

このブロックは main() 関数を呼び出します。main() 関数は、このライブラリが単独で実行されることを意図していないことを示すメッセージを標準出力に表示します。

This is library, not runnable

このメッセージの表示後、プログラムは終了します。これは、tkapplication.py が他のアプリケーションから import されて利用されることを想定した、ユーティリティライブラリであるためです。