Pythonのpkgutilモジュール徹底解説｜パッケージ拡張ユーティリティの使い方

特定のパッケージのモジュール検索パスを追加したり、パッケージ内に同梱されたリソースファイルを扱いたい場合には、Python標準ライブラリのpkgutilモジュールを使用します。pkgutilは、Pythonパッケージのインポート規則を変更するための各種関数を提供しており、さらにパッケージとして配布されるファイルからコード以外のリソースを読み込むことも可能です。

extend_path(path, name)

パッケージを構成するモジュール群の検索パスを拡張するための関数です。想定されている使い方は、パッケージの__init__.pyに以下のコードを記述することです。

import pkgutil
__path__ = pkgutil.extend_path(__path__, __name__)

extend_path()は、sys.pathを走査して、第2引数で指定されたパッケージ名と同じ名前のサブディレクトリを含むディレクトリを探します。見つかったディレクトリの一覧は、第1引数として渡されたpathと結合され、パッケージのインポートパスとしてそのまま使える単一のリストとして返されます。

主な関数一覧

find_loader(fullname)

指定したfullname（完全修飾モジュール名）に対応するモジュールローダーを取得します。
※なお、この関数はPython 3.12以降で非推奨となっているため、新しいコードではimportlibの利用が推奨されます。

get_importer(path_item)

指定したpath_itemに対応するファインダー（finder）オブジェクトを取得します。

get_loader(module_or_name)

module_or_nameで指定したモジュールのローダーオブジェクトを取得します。

iter_importers(fullname='')

指定したモジュール名に対応するファインダーオブジェクトを順番に生成（yield）するジェネレーターです。

iter_modules(path=None, prefix='')

path上に存在するすべてのサブモジュールのModuleInfoを順に返します。pathがNoneの場合は、sys.path上のすべてのトップレベルモジュールが対象となります。

>>> pk = pkgutil.iter_modules()
>>> for p in pk:
    print(p[1])

walk_packages(path=None, prefix='', onerror=None)

path上のすべてのモジュールを再帰的に走査し、ModuleInfoを順に返します。pathがNoneの場合は、アクセス可能なすべてのモジュールが対象になります。

import pkgutil
import sys

def explore_package(module_name):
    loader = pkgutil.get_loader(module_name)
    for sub_module in pkgutil.walk_packages([loader.filename]):
        _, sub_module_name, _ = sub_module
        qname = module_name + "." + sub_module_name
        print(qname)
        explore_package(qname)

ModuleInfoについて

ModuleInfo(module_finder, name, ispkg)は、モジュールに関する簡潔な情報を保持するnamedtupleを返します。各要素は次の通りです。

• module_finder： モジュールを見つけたファインダー
• name： モジュール名
• ispkg： パッケージである場合はTrue、通常のモジュールの場合はFalse

このようにpkgutilモジュールを活用することで、パッケージ構造の動的な探索や、プラグイン機構のような柔軟なモジュール読み込みを実現できます。