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

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

tkimport.py ライブラリは、Pythonモジュールのインポート処理をより堅牢かつユーザーフレンドリーにするためのユーティリティを提供します。特に、アプリケーションが必要とする外部モジュールが存在しない場合に、分かりにくいエラーで終了するのではなく、ユーザーに不足しているモジュールのインストール方法を案内することを目的としています。また、一度インポートしたモジュールをキャッシュすることで、複数回のインポートによるオーバーヘッドを避けることができます。

主な機能は以下の通りです。

モジュールのキャッシュインポート: 一度インポートに成功したモジュールは内部の辞書にキャッシュされ、次回以降の同じモジュールのインポート要求に対してはキャッシュされたオブジェクトを返します。
インポート失敗時の詳細なエラーハンドリング: モジュールのインポートに失敗した場合、原因となったエラーメッセージとともに、そのモジュールを pip や conda でインストールする方法の例を提示します。
プログラムの強制終了オプション: インポート失敗時に、警告として処理を続行するか、またはユーザー入力待ちの後、プログラムを強制終了するかを選択できます。
インポートエラーのサマリー表示: 複数のモジュールインポートで発生したエラーをまとめて表示し、ユーザーに不足しているすべてのモジュールを一度に把握させる機能を提供します。

このライブラリは、特にGUIアプリケーション（tklib との関連から推測されます）などのように、複数の外部依存を持つプログラムにおいて、起動時の依存モジュールチェックとそのフィードバックを標準化し、ユーザーエクスペリエンスを向上させる課題を解決します。

importする方法

tkimport.py ライブラリを他のPythonプログラムから利用するには、標準の import ステートメントを使用します。

ライブラリ全体をインポートする場合：

import tkimport

# tkimport.import_lib(...) や tkimport.messages(...) のようにアクセスします。

特定の関数のみをインポートする場合：

from tkimport import import_lib, messages

# import_lib(...) や messages(...) のように直接アクセスします。

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

tkimport.py ライブラリ自体は、標準ライブラリである importlib を利用しています。importlib はPythonに組み込まれているため、別途インストールする必要はありません。

ただし、tkimport.py のソースコードには以下の行が含まれており、tklib という非標準ライブラリに依存しています。

from tklib.tkobject import tkObject

このため、tkimport.py を実行する環境には tklib がインストールされている必要があります。tklib がインストールされていない場合、tkimport.py をインポートまたは直接実行した際に ModuleNotFoundError が発生し、プログラムは終了します。

tklib をインストールするには、pip コマンドを使用します。

pip install tklib

Pythonのバージョン管理や環境によっては、pip3 や conda を使用する場合もあります。

pip3 install tklib

conda install tklib

importできる変数と関数

tkimport.py から import できる主要な変数と関数は以下の通りです。

変数

imported_modules
- 説明: インポートに成功したモジュールをキャッシュする辞書です。キーはモジュール名（文字列）、値はインポートされたモジュールオブジェクトです。import_lib 関数によって内部的に管理されます。
error_modules
- 説明: インポートに失敗したモジュールと、その際に発生したエラーメッセージを記録する辞書です。キーはモジュール名（文字列）、値はエラーメッセージ（文字列）です。import_lib 関数と messages 関数によって参照・更新されます。

関数

import_lib(module_name, stop_by_error = True)
- 動作: 指定されたPythonモジュールをインポートします。既にインポート済みの場合はキャッシュからそのモジュールオブジェクトを返します。モジュールのインポートに失敗した場合、エラーメッセージを表示し、オプションでプログラムを終了させます。この関数は、外部ライブラリへの依存性を安全に管理するために使用されます。
- 引数:
  - module_name (str): インポートするモジュールの名前を指定します。例えば 'numpy' や 'matplotlib.pyplot' などです。
  - stop_by_error (bool, オプション): モジュールのインポートに失敗した場合の動作を制御します。
    - True (デフォルト): エラーメッセージを表示し、ユーザー入力待ちの後、プログラムを強制終了します。
    - False: 警告メッセージを表示し、None を返してプログラムの実行を続行します。
- 戻り値:
  - モジュールのインポートに成功した場合: インポートされたモジュールオブジェクト。
  - モジュールのインポートに失敗し、stop_by_error が False の場合: None。
  - モジュールのインポートに失敗し、stop_by_error が True の場合: プログラムは終了し、戻り値はありません。
messages(stop_by_error = True)
- 動作: import_lib 関数によって以前に発生したすべてのインポートエラーの概要を表示します。error_modules 辞書に記録されているエラーモジュールと、そのインストール方法の例をユーザーに提示します。エラーが見つかった場合、オプションでプログラムを終了させます。
- 引数:
  - stop_by_error (bool, オプション): error_modules にインポートエラーが記録されている場合の動作を制御します。
    - True (デフォルト): エラーのサマリーを表示し、ユーザー入力待ちの後、プログラムを強制終了します。
    - False: エラーのサマリーを警告として表示し、プログラムの実行を続行します。
- 戻り値:
  - error_modules が空（エラーなし）の場合: True。
  - error_modules にエラーが記録されており、stop_by_error が False の場合: False。
  - error_modules にエラーが記録されており、stop_by_error が True の場合: プログラムは終了し、戻り値はありません。

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

tkimport.py には、if __name__ == "__main__": ブロックが存在しません。このため、このスクリプトが直接実行された場合（例: python tkimport.py）、または他のプログラムから import tkimport としてインポートされた場合、以下のグローバルスコープのコードが上から順に実行されます。

importlib モジュールのチェックとインポート:
- 最初に、Pythonの標準ライブラリである importlib モジュールのインポートを試行します。
- もし何らかの理由で importlib のインポートに失敗した場合（極めて稀なケースですが）、エラーメッセージがコンソールに表示され、ユーザーが ENTER キーを押すまで待機した後、プログラムは終了します。
tklib.tkobject.tkObject のインポート:
- 次に、tklib ライブラリ内の tkobject モジュールから tkObject クラスをインポートします。
- 重要: この時点で tklib ライブラリがシステムにインストールされていない場合、ModuleNotFoundError が発生し、プログラムは直ちに終了します。これは tkimport.py が tklib に依存しているためです。
変数の初期化:
- imported_modules と error_modules の2つの辞書が、空の状態で初期化されます。これらの辞書は、後続の import_lib 関数や messages 関数によって使用および更新されます。

これらの初期化処理は、tkimport.py が提供する関数が正しく動作するために必要な準備ステップです。メインスクリプトとして実行しても、提供された関数を直接呼び出すコードは含まれていないため、上記以外の目に見える動作は発生しません。