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

ライブラリの機能や目的

tkparams.py ライブラリは、Pythonアプリケーションの設定パラメータを効率的に管理するための tkParams クラスを提供します。このモジュールは、以下の主要な機能と目的を持っています。

• パラメータの永続化: INIファイル形式でのパラメータの読み込みと保存をサポートし、アプリケーション設定の永続化を実現します。

• コマンドライン引数の管理: アプリケーション起動時のコマンドライン引数をパラメータとして取り扱い、設定に反映させることができます。

• パラメータの説明機能: 各パラメータに対して説明（docstringのようなもの）を付与し、パラメータの意図や使用方法を明確にできます。

• 柔軟なパラメータアクセス: 辞書ライクなアクセス、キーによる値の取得・設定、型に応じた値の変換（文字列、整数、浮動小数点数、ブール値）をサポートします。

• 表示機能: 現在のパラメータとその値を、オプションで説明と共に整形して表示する機能を提供します。

• 複合型パラメータのサポート: リスト、タプル、辞書などの複合型パラメータもINIファイルで管理できます。

このライブラリは、アプリケーションの設定を外部ファイルで管理し、動的に読み書きするニーズに応えることで、柔軟でメンテナンス性の高いアプリケーション開発を支援することを目的としています。

importする方法

tkparams.py ライブラリは、Pythonの標準的な import 文を使用して他のプログラムからインポートできます。

from tkparams import tkParams

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

tkparams.py は、tklib という非標準ライブラリに依存しています。具体的には、以下のモジュールを使用しています。

• tklib.tkobject

• tklib.tkutils

• tklib.tkinifile

• tklib.tkre

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

pip install tklib

もし上記のコマンドでインストールできない場合、tklib は特定のプロジェクトの内部ライブラリであるか、公開されていない可能性があります。その場合は、tklib のソースコードを入手し、Pythonのパスが通っている場所に配置する必要があります。

importできる変数と関数

tkparams.py からimportできる主要なクラスとそのメソッド、およびモジュールレベルの関数は以下の通りです。

クラス

class tkParams(tkObject)

アプリケーションの設定パラメータを管理するクラスです。tklib.tkobject.tkObject を継承しています。

• __init__(self, parameter_file=None, app=None, **args)

  • tkParams クラスの新しいインスタンスを初期化します。

  • parameter_file が指定された場合、そのINIファイルパスが内部的に保持されます。

  • app オブジェクトは、主にログ出力などのアプリケーション固有の機能と連携するために使用されます。

  • **args で渡されたキーワード引数は、初期パラメータとして設定されます。

  • 引数:

    • parameter_file (str, optional): パラメータを読み書きするINIファイルのパス。デフォルトはNone。

    • app (object, optional): 関連付けられるアプリケーションオブジェクト。デフォルトはNone。

    • args (dict): 初期設定として追加する任意のキーワード引数（パラメータ）。

  • 戻り値: なし

• __del__(self)

  • オブジェクトが破棄される際に呼び出されるデストラクタです。現在、特別な処理は行いません。

  • 引数: なし

  • 戻り値: なし

• __str__(self)

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

  • 引数: なし

  • 戻り値: str - このオブジェクトのクラスパスを示す文字列。

• dict(self)

  • このオブジェクトの属性を辞書として返します。これは self.__dict__ と同じです。

  • 引数: なし

  • 戻り値: dict - オブジェクトの __dict__ 属性。

• copy(self)

  • 現在のパラメータの新しいコピーを作成し、tkParams オブジェクトとして返します。

  • すべてのパラメータとその値を新しい tkParams インスタンスにコピーします。

  • 引数: なし

  • 戻り値: tkParams - 現在のパラメータを持つ新しい tkParams オブジェクト。

• get_param_dict(self)

  • このオブジェクトのパラメータ辞書を取得します。これは self.__dict__ と同じです。

  • 引数: なし

  • 戻り値: dict - オブジェクトの __dict__ 属性。

• get_path(self, path: str = None) -> str

  • 現在のパラメータファイルのパスを取得または設定します。

  • path が指定された場合、内部のパラメータファイルパスを更新し、その新しいパスを返します。

  • path がNoneの場合、現在の内部パスを返します。

  • 引数:

    • path (str, optional): 設定するパラメータファイルのパス。Noneの場合、現在のパスが返されます。デフォルトはNone。

  • 戻り値: str - 現在の（または更新された）パラメータファイルのパス。

• keys(self)

  • 現在のパラメータ辞書のキーのリストを返します。

  • 引数: なし

  • 戻り値: dict_keys - パラメータ辞書のすべてのキーを含む dict_keys オブジェクト。

• get(self, key: str, defval=None)

  • 指定されたキーのパラメータ値を取得します。

  • キーが存在しない場合、指定されたデフォルト値を返します。

  • 引数:

    • key (str): 取得するパラメータのキー。

    • defval (any, optional): キーが見つからなかった場合に返すデフォルト値。デフォルトはNone。

  • 戻り値: any - 指定されたキーのパラメータ値、またはデフォルト値。

• set(self, key: str, val, explanation: str = None)

  • 指定されたキーのパラメータ値を設定します。

  • オプションで、そのパラメータの説明を設定することもできます。

  • 引数:

    • key (str): 設定するパラメータのキー。

    • val (any): 設定するパラメータの値。

    • explanation (str, optional): パラメータの説明。デフォルトはNone。

  • 戻り値: any - 設定された値。

• set_attr(self, key: str, val, explanation: str = None)

  • 指定されたキーのパラメータ値を設定します。これは set メソッドのエイリアスです。

  • オプションで、そのパラメータの説明を設定することもできます。

  • 引数:

    • key (str): 設定するパラメータのキー。

    • val (any): 設定するパラメータの値。

    • explanation (str, optional): パラメータの説明。デフォルトはNone。

  • 戻り値: any - 設定された値。

• get_explanation(self, key: str) -> str

  • 指定されたキーのパラメータの説明を取得します。

  • 説明が見つからず、関連するアプリケーションオブジェクト (self._app) が存在する場合は、アプリケーションオブジェクトの翻訳機能（p() メソッド）を通じて説明を処理します。

  • 引数:

    • key (str): 説明を取得するパラメータのキー。

  • 戻り値: str or None - パラメータの説明、または説明が存在しない場合はNone。

• get_print_func(self, app, use_warning: bool) -> callable

  • 指定された条件に基づいて適切な出力関数を返します。

  • app オブジェクトと use_warning フラグに応じて、app.print_warning、app.print、または標準の print 関数を返します。

  • 引数:

    • app (object or None): アプリケーションオブジェクト。存在しない場合は標準出力が使用されます。

    • use_warning (bool): True の場合、app.print_warning を優先的に使用します。

  • 戻り値: callable - 出力に使用する関数。

• printinf(self, app=None, use_warning: bool = False)

  • 現在のすべてのパラメータとその値を、オプションで説明と共に標準出力または指定されたアプリケーションの出力関数を使用して表示します。

  • 引数:

    • app (object, optional): 出力に使用するアプリケーションオブジェクト。Noneの場合、内部の _app を使用します。デフォルトはNone。

    • use_warning (bool, optional): True の場合、警告出力関数（app.print_warning）を使用します。デフォルトはFalse。

  • 戻り値: なし

• print_parameters(self, heading: str = "", sort_by_keys: bool = True, exclude_keys: list = [], app=None, use_warning: bool = False)

  • 現在のパラメータとその値を整形して出力します。

  • 特定のキーを除外したり、キーでソートしたり、見出しを付けたりすることができます。

  • アンダースコア (_) で始まるキーや値がNoneのキーはデフォルトで出力されません。

  • 引数:

    • heading (str, optional): 出力の冒頭に表示する見出し文字列。デフォルトは空文字列。

    • sort_by_keys (bool, optional): True の場合、キーをアルファベット順（大文字小文字を区別しない）でソートして表示します。デフォルトはTrue。

    • exclude_keys (list of str, optional): 出力から除外するキーのリスト。デフォルトは空リスト。

    • app (object, optional): 出力に使用するアプリケーションオブジェクト。Noneの場合、内部の _app を使用します。デフォルトはNone。

    • use_warning (bool, optional): True の場合、警告出力関数（app.print_warning）を使用します。デフォルトはFalse。

  • 戻り値: なし

• print_parameters_warning(self, heading: str = "", sort_by_keys: bool = True, app=None)

  • 現在のパラメータとその値を警告として出力します。

  • app オブジェクトの print_warning メソッドを使用します。

  • アンダースコア (_) で始まるキーや値がNoneのキーはデフォルトで出力されません。

  • 引数:

    • heading (str, optional): 出力の冒頭に表示する見出し文字列。デフォルトは空文字列。

    • sort_by_keys (bool, optional): True の場合、キーをアルファベット順（大文字小文字を区別しない）でソートして表示します。デフォルトはTrue。

    • app (object, optional): 出力に使用するアプリケーションオブジェクト。Noneの場合、内部の _app を使用します。デフォルトはNone。

  • 戻り値: なし

• get_string(self, path: str = None, section: str = None, key: str = None, def_val: str = None, is_print: bool = False)

  • INIファイルから文字列型のパラメータ値を読み込みます。

  • 指定されたパス、セクション、キーに基づいて値を読み込みます。

  • 引数:

    • path (str, optional): INIファイルのパス。Noneの場合、現在の内部パスを使用します。デフォルトはNone。

    • section (str, optional): パラメータが属するセクション名。デフォルトはNone。

    • key (str, optional): 取得するパラメータのキー。デフォルトはNone。

    • def_val (str, optional): キーが見つからなかった場合に返すデフォルト値。デフォルトはNone。

    • is_print (bool, optional): 処理中にメッセージを出力するかどうか。デフォルトはFalse。

  • 戻り値: str or None - 指定されたキーの文字列値、またはデフォルト値、またはNone。

    • 注意: コード中の IsPrint は未定義のグローバル変数であり、エラーを引き起こす可能性があります。

• write_string(self, path: str = None, section: str = None, key: str = None, value=None, outfile=None, is_print: bool = False)

  • INIファイルに文字列型のパラメータ値を書き込みます。

  • 指定されたパス、セクション、キー、値に基づいてファイルを更新します。

  • 引数:

    • path (str, optional): INIファイルのパス。Noneの場合、現在の内部パスを使用します。デフォルトはNone。

    • section (str, optional): パラメータが属するセクション名。デフォルトはNone。

    • key (str, optional): 書き込むパラメータのキー。デフォルトはNone。

    • value (any, optional): 書き込むパラメータの値。str() で文字列に変換されます。デフォルトはNone。

    • outfile (any, optional): 出力ファイルオブジェクト（使用されていない可能性が高い）。デフォルトはNone。

    • is_print (bool, optional): 処理中にメッセージを出力するかどうか。デフォルトはFalse。

  • 戻り値: bool or None - 書き込みが成功した場合はTrue、失敗した場合はFalse。tkIniFile のインスタンス化に失敗した場合はNone。

    • 注意: 内部で write_string(self, ...) となっている部分は、ini.write_string(...) の間違いである可能性が高いですが、現状のコードをそのまま説明しています。また、IsPrint は未定義のグローバル変数であり、エラーを引き起こす可能性があります。

• read_parameters(self, path: str = None, section: str = None, AddSection: bool = False, ignore_keys: list = [], terminator: str = None, IsPrint: bool = True, follow_vartype: bool = True, read_inifile: bool = False)

  • INIファイルからすべてのパラメータを読み込み、現在のオブジェクトに適用します。

  • 読み込んだ値は、既存のパラメータの型に基づいて型変換されます。リスト、タプル、辞書などの複合型もサポートします。

  • 引数:

    • path (str, optional): INIファイルのパス。Noneの場合、現在の内部パスを使用します。デフォルトはNone。

    • section (str, optional): 読み込むセクション名。Noneの場合、すべてのセクションを読み込みます。デフォルトはNone。

    • AddSection (bool, optional): 読み込んだセクションをパラメータとして追加するかどうか。デフォルトはFalse。

    • ignore_keys (list of str, optional): 読み込み時に無視するキーのリスト。デフォルトは空リスト。

    • terminator (str, optional): 値の終端を示す文字。これ以降の文字列は無視されます。デフォルトはNone。

    • IsPrint (bool, optional): 処理中にメッセージを出力するかどうか。デフォルトはTrue。

    • follow_vartype (bool, optional): True の場合、既存のパラメータの型に合わせて読み込んだ値を変換します。False の場合、pconv を使用して変換します。デフォルトはTrue。

    • read_inifile (bool, optional): True の場合、INIファイル自体に関する情報を読み込みます。デフォルトはFalse。

  • 戻り値: dict or None - 読み込まれたパラメータを含む辞書、またはINIファイルが存在しない場合はNone。

• save_parameters_by_keys(self, prmfile: str, heading: str = None, section: str = None, keys: list = None, exclude_keys: list = [], save_commandline: bool = False)

  • 指定されたキーのパラメータのみをINIファイルに保存します。

  • このメソッドは、save_parameters メソッドから特定のキーセットを保存するために呼び出されるヘルパーメソッドです。

  • 引数:

    • prmfile (str): パラメータを保存するINIファイルのパス。

    • heading (str, optional): ファイル内のセクションの前に挿入される見出し（使用されていない可能性が高い）。デフォルトはNone。

    • section (str, optional): パラメータを保存するセクション名。デフォルトはNone。

    • keys (list of str, optional): 保存するパラメータのキーのリスト。Noneの場合、params.keys() が使用されます。デフォルトはNone。

    • exclude_keys (list of str, optional): 保存から除外するキーのリスト。デフォルトは空リスト。

    • save_commandline (bool, optional): コマンドライン引数を保存するかどうか。デフォルトはFalse。

  • 戻り値: なし（実際には tkIniFile.write_string の結果が使用されますが、このメソッド自体は何も返しません）。

    • 注意: 内部で keys = list(params.keys()) となっている部分は、params がこのスコープで未定義であり、エラーを引き起こす可能性があります。おそらく self.keys() を意図していると考えられますが、現状のコードをそのまま説明しています。

• save_parameters(self, path: str = None, section: str = 'Preferences', keys: list = None, exclude_keys: list = [], otherparams: dict = None, sort_by_keys: bool = True, other_section: str = 'OtherParameters', update_commandline: bool = True, save_commandline: bool = False, save_inifile: bool = False, IsPrint: bool = True)

  • 現在のすべてのパラメータをINIファイルに保存します。

  • パラメータはセクションにまとめられ、キーと値のペアとして保存されます。リストや辞書のような複合型のパラメータも適切に保存されます。

  • 引数:

    • path (str, optional): INIファイルのパス。Noneの場合、現在の内部パスを使用します。デフォルトはNone。

    • section (str, optional): 主要なパラメータを保存するセクション名。デフォルトは'Preferences'。

    • keys (list of str, optional): 保存するパラメータのキーのリスト。Noneの場合、すべてのパラメータが保存されます。デフォルトはNone。

    • exclude_keys (list of str, optional): 保存から除外するキーのリスト。デフォルトは空リスト。

    • otherparams (dict, optional): 別のセクションに保存する追加のパラメータ辞書。デフォルトはNone。

    • sort_by_keys (bool, optional): True の場合、キーをアルファベット順（大文字小文字を区別しない）でソートして保存します。デフォルトはTrue。

    • other_section (str, optional): otherparams を保存するセクション名。デフォルトは'OtherParameters'。

    • update_commandline (bool, optional): True の場合、現在のコマンドライン引数を commandline パラメータとして更新します。デフォルトはTrue。

    • save_commandline (bool, optional): True の場合、commandline パラメータも保存します。デフォルトはFalse。

    • save_inifile (bool, optional): True の場合、inifile パラメータも保存します。デフォルトはFalse。

    • IsPrint (bool, optional): 処理中にメッセージを出力するかどうか。デフォルトはTrue。

  • 戻り値: bool - 保存が成功した場合はTrue、失敗した場合はFalse。

関数

def main()

このモジュールがスクリプトとして直接実行されたときに呼び出されるメイン関数です。

• 動作: このモジュールがライブラリとして使用されることを意図しているため、直接実行された場合はその旨のメッセージを標準出力に表示します。

• 引数: なし

• 戻り値: なし

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

tkparams.py ファイルがPythonインタープリタによって直接実行された場合、ファイルの末尾にある if __name__ == "__main__": ブロックが実行されます。このブロック内では main() 関数が呼び出されます。

main() 関数は、このモジュールがライブラリとして設計されており、直接実行されることを想定していない旨のメッセージを標準出力に出力します。

出力されるメッセージは以下の通りです。

This is library, not runnable

これは、ユーザーが誤ってライブラリファイルを直接実行してしまった場合に、その目的を伝えるための一般的なプラクティスです。