tkobject.py Library Technical Documentation

ライブラリの機能や目的

tkobject.py ライブラリは、Python オブジェクトの基本クラス tkObject を提供します。このクラスは、オブジェクトの属性管理、リフレクション、デバッグ機能、および一般的なユーティリティメソッドを強化することを目的としています。

主な機能:

• 強化された属性管理: 通常の属性アクセスに加えて、tkObject.get2() や tkObject.set_attribute2() メソッドを通じて、obj.data[0] や obj.config["key"] のようなリストや辞書内の要素へのアクセスを文字列ベースで抽象化します。

• オブジェクトのイントロスペクション: オブジェクトのクラス、メンバー関数、メンバー変数、および属性辞書 (__dict__) へのアクセスを容易にするメソッドを提供します。

• デバッグサポート: デバッグレベルに基づいて条件付きでメッセージを出力したり、オブジェクトの内容をプリティプリントしたりする機能 (dprint, dpprint) を備えています。

• 汎用ユーティリティ: 属性の一括更新、エラーメッセージの標準化、クラスパスの取得など、オブジェクト指向プログラミングで頻繁に必要となる補助的な機能を提供します。

解決する課題:

このライブラリは、主に以下の課題を解決します。

• 一貫したオブジェクト操作インターフェース: 複雑なデータ構造を持つオブジェクトに対して、文字列ベースで統一された属性アクセスと操作のメカニズムを提供します。

• オブジェクトのメタデータへの容易なアクセス: オブジェクトの構造を動的に調べ、そのメンバーや属性に関する情報を取得するプロセスを簡素化します。

• 効率的なデバッグ: デバッグメッセージの表示を集中管理し、特定のデバッグレベルでのみ出力することで、ログの量を制御しやすくします。

importする方法

このライブラリの tkObject クラスを他の Python プログラムから利用するには、以下の import 文を使用します。

from tkobject import tkObject

なお、_analyze_varstr 関数は内部ヘルパー関数であり、通常は直接インポートして使用するものではありません。

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

tkobject.py ライブラリは、標準の Python ライブラリのみを使用しており、追加の非標準ライブラリを必要としません。

内部的に以下の標準ライブラリを使用しています。

• pprint: オブジェクトを読みやすい形式で出力するために使用されます。

• re: 正規表現を使用して文字列を解析するために使用されます。

• sys: FunctionName メソッドで現在のフレーム情報を取得するために使用されますが、ソースコードの最上部には import sys が明示的に記述されていません。もし FunctionName を使用して NameError が発生する場合は、ライブラリの利用側で import sys を行うか、tkobject.py の最上部に import sys を追加する必要があります。

したがって、pip コマンドなどを使った特別なインストールは不要です。

importできる変数と関数

このライブラリから主にインポートして利用できるのは tkObject クラスです。

クラス: tkObject

オブジェクトの基本機能とユーティリティを提供する基底クラスです。

クラス変数

• debug

  • 説明: デバッグメッセージの出力レベルを制御する整数値。dprint および dpprint メソッドがこの値に基づいて出力を制御します。

• debug_explicit

  • 説明: 明示的なデバッグ処理を制御するフラグ。現在の実装では update メソッド内でコメントアウトされており、実質的には使用されていません。

メソッド

• __del__(self)

  • 動作: オブジェクトが破棄される際に呼び出されるデストラクタ。現在の実装では何も行いません。

  • 引数: なし

  • 戻り値: なし

• __str__(self)

  • 動作: オブジェクトの文字列表現を返します。ModuleName.ClassName の形式です。

  • 引数: なし

  • 戻り値: オブジェクトのモジュール名とクラス名を含む文字列。

• hasattr(self, attribute)

  • 動作: 指定された attribute がオブジェクトに存在するかどうかをチェックします。Python の組み込み hasattr() と同様の機能です。

  • 引数:

    • attribute (str): チェックする属性の名前。

  • 戻り値: 属性が存在すれば True、そうでなければ False。

• callable(self, method)

  • 動作: 指定された method がオブジェクトの呼び出し可能な属性（関数やメソッド）であるかどうかをチェックします。Python の組み込み callable() と getattr() を組み合わせて使用します。

  • 引数:

    • method (str): チェックするメソッドの名前。

  • 戻り値: 呼び出し可能であれば True、そうでなければ False。

• exec_method(self, method, *args, **kwarg)

  • 動作: 指定された method をオブジェクト上で実行します。メソッドが存在し、かつ呼び出し可能であれば、引数 *args とキーワード引数 **kwargs を渡して実行します。

  • 引数:

    • method (str): 実行するメソッドの名前。

    • *args: メソッドに渡す位置引数。

    • **kwarg: メソッドに渡すキーワード引数。

  • 戻り値: なし (メソッドの戻り値を直接返しません)。

• get_class(self)

  • 動作: オブジェクトのクラスオブジェクトを返します。

  • 引数: なし

  • 戻り値: オブジェクトのクラスを表す type オブジェクト。

• get_attributes(self)

  • 動作: オブジェクトのクラスで定義されているすべての属性名（メソッド、変数を含む）のリストを返します。dir(self.__class__) と同じです。

  • 引数: なし

  • 戻り値: 属性名のリスト。

• get_member_functions(self, obj=None)

  • 動作: 指定されたオブジェクト（または自身のオブジェクト）のクラスで定義されている、呼び出し可能なメンバー（メソッド）の名前のリストを返します。

  • 引数:

    • obj (object, optional): メンバー関数を取得する対象オブジェクト。指定しない場合、自身のオブジェクト (self) が対象となります。

  • 戻り値: メンバー関数名のリスト。

• get_member_variables(self, obj=None)

  • 動作: 指定されたオブジェクト（または自身のオブジェクト）のクラスで定義されている、呼び出し可能ではないメンバー（変数）の名前のリストを返します。

  • 引数:

    • obj (object, optional): メンバー変数を取得する対象オブジェクト。指定しない場合、自身のオブジェクト (self) が対象となります。

  • 戻り値: メンバー変数名のリスト。

• get_dict(self)

  • 動作: オブジェクトのインスタンス辞書 (__dict__) を返します。これにはインスタンス固有の属性が格納されています。

  • 引数: なし

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

• get_members(self)

  • 動作: オブジェクトのクラスで定義されているメンバー関数、メンバー変数、およびインスタンス辞書をそれぞれリストと辞書として返します。

  • 引数: なし

  • 戻り値: (メンバー関数名のリスト, メンバー変数名のリスト, インスタンス辞書) のタプル。

• get(self, key, defval=None)

  • 動作: オブジェクトのインスタンス辞書から指定された key の値を取得します。key が存在しない場合は defval を返します。Python の辞書 dict.get() と同様の動作です。

  • 引数:

    • key (str): 取得する属性のキー。

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

  • 戻り値: key に対応する値、または defval。

• set_attribute(self, key, val)

  • 動作: オブジェクトのインスタンス辞書に指定された key で val を設定します。

  • 引数:

    • key (str): 設定する属性のキー。

    • val (any): 設定する値。

  • 戻り値: なし

• get2(self, key, defval=None)

  • 動作: obj.varname[index] や obj.dict["key"] のような形式の文字列を解析し、インスタンス属性とそのサブ要素にアクセスします。

  • 引数:

    • key (str): varname または varname[index] / varname("key") の形式の文字列。

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

  • 戻り値: 指定された属性またはそのサブ要素の値。varname が見つからない場合は defval。

• set_attribute2(self, key, val, assign_dict_element_vars=False)

  • 動作: obj.varname[index] = val や obj.dict["key"] = val のような形式の文字列を解析し、インスタンス属性とそのサブ要素に値を設定します。assign_dict_element_vars が True の場合、元の key も辞書に追加されますが、これは通常の使用方法ではありません。

  • 引数:

    • key (str): varname または varname[index] / varname("key") の形式の文字列。

    • val (any): 設定する値。

    • assign_dict_element_vars (bool, optional): 特殊な動作を制御するフラグ。デフォルトは False。

  • 戻り値: なし

• update(self, check_defined=False, **kwargs)

  • 動作: キーワード引数 kwargs を使用して、オブジェクトの複数の属性を一括で更新します。check_defined が True の場合、更新しようとしているキーがすでにオブジェクトに存在するかどうかをチェックし、存在しない場合はエラーメッセージを出力してプログラムを終了します。

  • 引数:

    • check_defined (bool, optional): 更新対象のキーが事前に定義されているかチェックするかどうか。デフォルトは False。

    • **kwargs: 更新する属性名とその値のペア。

  • 戻り値: なし

• print_attributes(self, print_header=1)

  • 動作: オブジェクトのすべてのインスタンス属性（__dict__ に含まれるもの）を整形して出力します。

  • 引数:

    • print_header (int, optional): ヘッダー行 (attributes in Module.Class) を出力するかどうか。1 の場合に出力。デフォルトは 1。

  • 戻り値: なし

• debugprint(self, level, *args)

  • 動作: self.dprint メソッドのエイリアスです。

  • 引数:

    • level (int): このメッセージを出力するための最低デバッグレベル。

    • *args: 出力する内容。

  • 戻り値: なし

• dprint(self, level, *args)

  • 動作: オブジェクトの debug レベルが指定された level 以上の場合に、引数 *args を標準出力に出力します。

  • 引数:

    • level (int): このメッセージを出力するための最低デバッグレベル。

    • *args: 出力する内容。

  • 戻り値: なし

• debugpprint(self, level, *args)

  • 動作: self.dpprint メソッドのエイリアスです。

  • 引数:

    • level (int): このメッセージを出力するための最低デバッグレベル。

    • *args: プリティプリントする内容。

  • 戻り値: なし

• dpprint(self, level, *args)

  • 動作: オブジェクトの debug レベルが指定された level 以上の場合に、pprint モジュールを使用して引数 *args をプリティプリントします。

  • 引数:

    • level (int): このメッセージを出力するための最低デバッグレベル。

    • *args: プリティプリントする内容。

  • 戻り値: なし

• IfYes(self, condition, vartrue, varfalse)

  • 動作: condition が True の場合は vartrue を、False の場合は varfalse を返します。三項演算子 (vartrue if condition else varfalse) の代替です。

  • 引数:

    • condition (bool): 評価する条件。

    • vartrue (any): 条件が True の場合に返す値。

    • varfalse (any): 条件が False の場合に返す値。

  • 戻り値: vartrue または varfalse。

• errormsg(self, funcname, str)

  • 動作: 指定された関数名とエラーメッセージを含む整形されたエラー文字列を標準出力に出力します。

  • 引数:

    • funcname (str): エラーが発生した関数名。

    • str (str): エラーメッセージの内容。

  • 戻り値: なし

• ModuleName(self)

  • 動作: オブジェクトが属するモジュールの名前を返します。

  • 引数: なし

  • 戻り値: モジュール名を示す文字列 (__name__ の値)。

• ClassName(self)

  • 動作: オブジェクトのクラス名を返します。

  • 引数: なし

  • 戻り値: クラス名を示す文字列 (self.__class__.__name__ の値)。

• FunctionName(self)

  • 動作: このメソッドを呼び出した関数（またはメソッド）の名前を返します。sys モジュールを使用します。このメソッドが実行される環境で sys がインポートされている必要があります。

  • 引数: なし

  • 戻り値: 呼び出し元の関数名を示す文字列。

• ClassPath(self)

  • 動作: オブジェクトの完全なクラスパスを ModuleName.ClassName の形式で返します。

  • 引数: なし

  • 戻り値: モジュール名とクラス名を組み合わせた文字列。

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

tkobject.py のソースコードには、if __name__ == "__main__": ブロックが含まれていません。したがって、このファイルを直接 Python インタープリタで実行しても、特別な処理は行われません。

ファイルを直接実行した場合、単に tkObject クラスと _analyze_varstr 関数がメモリに読み込まれ、定義されるだけです。実際の機能を使用するには、他の Python スクリプトから tkobject.py をインポートし、tkObject クラスをインスタンス化する必要があります。