tkparams.py ライブラリ技術ドキュメント

ライブラリの機能や目的

tkparams.py は、アプリケーションのパラメータ管理を目的としたPythonライブラリです。主にINIファイル形式の設定ファイルとの間でパラメータを読み書きし、管理するための tkParams クラスを提供します。このライブラリの主な機能と解決する課題は以下の通りです。

INIファイルからのパラメータ読み込み: 設定ファイル（INI形式）から、アプリケーションが必要とする多様なデータ型（文字列、数値、真偽値、リスト、辞書など）のパラメータを効率的に読み込みます。
パラメータの永続化: 現在のアプリケーションの状態やユーザー設定をINIファイルに保存し、次回の起動時に復元できるようにします。
パラメータ管理とアクセス: オブジェクト指向のインターフェースを通じて、名前（キー）でパラメータにアクセスし、その値を設定・取得できます。
パラメータへの説明付与: 各パラメータに説明文を付与し、デバッグやドキュメント作成時に役立つ情報を提供します。
コマンドライン引数の記録: アプリケーションが実行された際のコマンドライン引数をパラメータとして記録する機能を提供します。
多様なデータ型のサポート: 文字列だけでなく、数値や真偽値、さらにはリストや辞書形式のパラメータもINIファイルで管理できます。

このライブラリは、特にGUIアプリケーションや、多数の設定項目を持つスクリプトにおいて、設定管理の複雑さを軽減し、コードの保守性を向上させることを目指しています。

importする方法

tkparams.py ライブラリを他のPythonプログラムから利用するには、tkParams クラスをインポートします。

from tkparams import tkParams

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

tkparams.py は、以下の非標準ライブラリ（tklib パッケージの一部）に依存しています。

tklib.tkobject
tklib.tkutils
tklib.tkinifile
tklib.tkre

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

pip install tklib

importできる変数と関数

tkparams.py ライブラリは、主に tkParams クラスと、スクリプトが直接実行されたときに呼び出される main 関数を提供します。

クラス

`tkParams`

INIファイルベースのパラメータ管理機能を提供するクラスです。tklib.tkobject.tkObject を継承しています。

__init__(self, parameter_file=None, app=None, **args)
- tkParams クラスのコンストラクタです。
- 引数:
  - parameter_file (str, オプション): 管理するINIファイルのパス。
  - app (object, オプション): tklib.tkapp.tkApp などのアプリケーションオブジェクト。パラメータの説明文の翻訳やログ出力に利用されます。
  - **args: オブジェクトの初期属性として設定される任意のキーワード引数。
- 戻り値: なし
__del__(self)
- デストラクタです。特別な処理は行いません。
- 引数: なし
- 戻り値: なし
__str__(self)
- オブジェクトの文字列表現を返します。ClassPath() メソッドの結果（クラスの完全パス）を返します。
- 引数: なし
- 戻り値: str - クラスの完全パス。
dict(self)
- tkParams オブジェクトの内部辞書（__dict__）を返します。これには、インスタンスに設定された全てのパラメータと内部変数が含まれます。
- 引数: なし
- 戻り値: dict - オブジェクトの内部辞書。
copy(self)
- 現在の tkParams オブジェクトのシャローコピーを作成し、新しい tkParams オブジェクトとして返します。
- 引数: なし
- 戻り値: tkParams - 新しい tkParams オブジェクトのインスタンス。
get_param_dict(self)
- dict() メソッドと同じく、tkParams オブジェクトの内部辞書（__dict__）を返します。
- 引数: なし
- 戻り値: dict - オブジェクトの内部辞書。
get_path(self, path)
- INIファイルのパスを取得または設定します。
- 引数:
  - path (str, オプション): 新しいINIファイルのパス。None の場合、現在のパスを返します。
- 戻り値: str - 現在設定されているINIファイルのパス。
keys(self)
- オブジェクトに設定されているパラメータのキーを返します。
- 引数: なし
- 戻り値: dict_keys - パラメータキーのビュー。
get(self, key, defval=None)
- 指定された key に対応するパラメータの値を返します。key が存在しない場合は defval を返します。
- 引数:
  - key (str): 取得したいパラメータの名前。
  - defval (any, オプション): パラメータが存在しない場合に返すデフォルト値。デフォルトは None。
- 戻り値: any - パラメータの値、またはデフォルト値。
set(self, key, val, explanation=None)
- 指定された key に val を設定し、オプションで説明文 explanation を関連付けます。
- 引数:
  - key (str): 設定したいパラメータの名前。
  - val (any): 設定する値。
  - explanation (str, オプション): パラメータの説明文。
- 戻り値: any - 設定された値 val。
set_attr(self, key, val, explanation=None)
- set() メソッドのエイリアスです。機能は set() と全く同じです。
- 引数:
  - key (str): 設定したいパラメータの名前。
  - val (any): 設定する値。
  - explanation (str, オプション): パラメータの説明文。
- 戻り値: any - 設定された値 val。
get_explanation(self, key)
- 指定された key に関連付けられた説明文を返します。app オブジェクトが設定されている場合、説明文は翻訳される可能性があります。
- 引数:
  - key (str): 説明を取得したいパラメータの名前。
- 戻り値: str または None - パラメータの説明文、または説明が設定されていない場合は None。
get_print_func(self, app, use_warning)
- パラメータ出力に使用する関数 (print、app.print、または app.print_warning) を決定し、返します。
- 引数:
  - app (object): アプリケーションオブジェクト。
  - use_warning (bool): True の場合、app.print_warning を優先して使用します。
- 戻り値: function - ログ出力に使用する関数。
printinf(self, app=None, use_warning=False)
- 全てのパラメータとその値、および設定されている場合は説明文をコンソールに出力します。
- 引数:
  - app (object, オプション): アプリケーションオブジェクト。指定しない場合、インスタンスの _app 属性を使用します。
  - use_warning (bool, オプション): True の場合、警告メッセージとして出力します。
- 戻り値: なし
print_parameters(self, heading="", sort_by_keys=True, exclude_keys=[], app=None, use_warning=False)
- 特定の条件に基づいてパラメータ情報をコンソールに出力します。キーでソートしたり、特定のキーを除外したりできます。アンダースコア _ で始まるキーや値が None のキーはスキップされます。
- 引数:
  - heading (str, オプション): 出力の冒頭に表示する見出し。
  - sort_by_keys (bool, オプション): True の場合、キーのアルファベット順（大文字小文字を区別しない）でソートして出力します。
  - exclude_keys (list, オプション): 出力から除外するキーのリスト。
  - app (object, オプション): アプリケーションオブジェクト。指定しない場合、インスタンスの _app 属性を使用します。
  - use_warning (bool, オプション): True の場合、警告メッセージとして出力します。
- 戻り値: なし
print_parameters_warning(self, heading="", sort_by_keys=True, app=None)
- print_parameters と同様にパラメータ情報を出力しますが、必ず app.print_warning を使用して警告として出力します。アンダースコア _ で始まるキーや値が None のキーはスキップされます。
- 引数:
  - heading (str, オプション): 出力の冒頭に表示する見出し。
  - sort_by_keys (bool, オプション): True の場合、キーのアルファベット順（大文字小文字を区別しない）でソートして出力します。
  - app (object, オプション): アプリケーションオブジェクト。指定しない場合、インスタンスの _app 属性を使用します。
- 戻り値: なし
get_string(self, path=None, section=None, key=None, def_val=None, is_print=False)
- 指定されたINIファイルから、セクションとキーに対応する文字列値を取得します。
- 引数:
  - path (str, オプション): INIファイルのパス。None の場合、オブジェクトに設定されているパスを使用します。
  - section (str, オプション): 読み込むセクション名。
  - key (str, オプション): 読み込むキー名。
  - def_val (str, オプション): キーが存在しない場合に返すデフォルト値。
  - is_print (bool, オプション): 読み込み処理に関する情報を出力するかどうか。
- 戻り値: str - 読み込んだ文字列値、またはデフォルト値。
write_string(self, path=None, section=None, key=None, value=None, outfile=None, is_print=False)
- 指定されたINIファイルに、セクションとキーに対応する文字列値を書き込みます。
- 引数:
  - path (str, オプション): INIファイルのパス。None の場合、オブジェクトに設定されているパスを使用します。
  - section (str, オプション): 書き込むセクション名。
  - key (str, オプション): 書き込むキー名。
  - value (str, オプション): 書き込む値。
  - outfile (file object, オプション): 出力先のファイルオブジェクト。指定しない場合、path で指定されたファイルに書き込みます。
  - is_print (bool, オプション): 書き込み処理に関する情報を出力するかどうか。
- 戻り値: any - write_string 関数の戻り値。 (注: このメソッドは、tkIniFile オブジェクトの write_string メソッドではなく、外部の write_string 関数を呼び出そうとします。しかし、そのような関数はライブラリ内で定義されていません。)
read_parameters(self, path=None, section=None, AddSection=False, ignore_keys=[], terminator=None, IsPrint=True, follow_vartype=True, read_inifile=False)
- INIファイルからパラメータを読み込み、現在の tkParams オブジェクトの属性として設定します。リスト、タプル、辞書などの複合型も処理します。
- 引数:
  - path (str, オプション): INIファイルのパス。None の場合、オブジェクトに設定されているパスを使用します。
  - section (str, オプション): 読み込むセクション名。
  - AddSection (bool, オプション): True の場合、セクション名もキーの一部として追加します。
  - ignore_keys (list, オプション): 読み込みを無視するキーのリスト。
  - terminator (str, オプション): 値の終端を示す文字列。この文字列以降は無視されます（例: コメント区切り）。
  - IsPrint (bool, オプション): 読み込み処理に関する情報を出力するかどうか。
  - follow_vartype (bool, オプション): True の場合、既存のパラメータの型に合わせて読み込んだ値を変換します。
  - read_inifile (bool, オプション): True の場合、inifile キーを読み込みます。
- 戻り値: dict または None - 読み込んだ全パラメータを含む辞書、またはエラー発生時は None。
save_parameters_by_keys(self, prmfile, heading=None, section=None, keys=None, exclude_keys=[], save_commandline=False)
- 指定されたキーのパラメータのみをINIファイルに保存します。
- 引数:
  - prmfile (str): 保存先のINIファイルのパス。
  - heading (str, オプション): INIファイルに書き込む見出し（コメント）。
  - section (str, オプション): 書き込むセクション名。
  - keys (list, オプション): 保存するキーのリスト。None の場合、全てのキーが対象となります。
  - exclude_keys (list, オプション): 保存から除外するキーのリスト。
  - save_commandline (bool, オプション): True の場合、commandline パラメータも保存します。
- 戻り値: なし
save_parameters(self, path=None, section='Preferences', keys=None, exclude_keys=[], otherparams=None, sort_by_keys=True, other_section='OtherParameters', update_commandline=True, save_commandline=False, save_inifile=False, IsPrint=True)
- 現在の tkParams オブジェクトの全てのパラメータをINIファイルに保存します。コマンドライン引数、リスト、辞書などの複合型も適切に処理します。
- 引数:
  - path (str, オプション): 保存先のINIファイルのパス。None の場合、オブジェクトに設定されているパスを使用します。
  - section (str, オプション): メインのパラメータを書き込むセクション名。デフォルトは 'Preferences'。
  - keys (list, オプション): 保存するキーのリスト。None の場合、tkParams オブジェクトの全ての属性が対象となります。
  - exclude_keys (list, オプション): 保存から除外するキーのリスト。
  - otherparams (dict, オプション): 別のセクションに保存する追加パラメータの辞書。
  - sort_by_keys (bool, オプション): True の場合、キーのアルファベット順（大文字小文字を区別しない）でソートして保存します。
  - other_section (str, オプション): otherparams を書き込むセクション名。デフォルトは 'OtherParameters'。
  - update_commandline (bool, オプション): True の場合、現在のコマンドライン引数を commandline パラメータとして更新します。
  - save_commandline (bool, オプション): True の場合、commandline パラメータもINIファイルに保存します。
  - save_inifile (bool, オプション): True の場合、inifile パラメータも保存します。
  - IsPrint (bool, オプション): 保存処理に関する情報を出力するかどうか。
- 戻り値: bool - 保存が成功した場合は True、失敗した場合は False。

関数

`main()`

main()
- スクリプトが直接実行された際に呼び出される関数です。このライブラリが実行可能ではないことを示すメッセージを標準出力に出力します。
- 引数: なし
- 戻り値: なし

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

tkparams.py ファイルを直接Pythonインタープリタで実行した場合、if __name__ == "__main__": ブロック内の main() 関数が呼び出されます。この main() 関数は、以下のメッセージを標準出力に出力します。

This is library, not runnable

これは、tkparams.py が単独で実行されることを意図したアプリケーションではなく、他のPythonプログラムからインポートされて使用されるライブラリであることを示しています。