pkgutil --- パッケージ拡張ユーティリティ

ソースコード: Lib/pkgutil.py

このモジュールはインポートシステムの、特にパッケージサポートに関するユーティリティです。

class pkgutil.ModuleInfo(module_finder, name, ispkg)

モジュールの概要情報を格納する namedtuple

バージョン 3.6 で追加.

pkgutil.extend_path(path, name)

パッケージを構成するモジュールの検索パスを拡張します。パッケージの __init__.py で次のように書くことを意図したものです:

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

上記はパッケージの __path__ に sys.path の全ディレクトリのサブディレクトリとしてパッケージ名と同じ名前を追加します。これは1つの論理的なパッケージの異なる部品を複数のディレクトリに分けて配布したいときに役立ちます。

同時に *.pkg の * の部分が name 引数に指定された文字列に一致するファイルの検索もおこないます。この機能は import で始まる特別な行がないことを除き *.pth ファイルに似ています (site の項を参照)。 *.pkg は重複のチェックを除き、信頼できるものとして扱われます。 *.pkg ファイルの中に見つかったエントリはファイルシステム上に実在するか否かを問わず、そのまますべてパスに追加されます。(このような仕様です。)

入力パスがリストでない場合(フリーズされたパッケージのとき)は何もせずにリターンします。入力パスが変更されていなければ、アイテムを末尾に追加しただけのコピーを返します。

sys.path はシーケンスであることが前提になっています。 sys.path の要素の内、実在するディレクトリを指す文字列となっていないものは無視されます。ファイル名として使ったときにエラーが発生する sys.path の Unicode要素がある場合、この関数(os.path.isdir() を実行している行) で例外が発生する可能性があります。

class pkgutil.ImpImporter(dirname=None)

Python の「旧式の」インポートアルゴリズムをラップする、 PEP 302 に基づく Finder です。

dirname が文字列の場合、そのディレクトリを検索する PEP 302 finder を作成します。 dirname が None のとき、現在の sys.path とフリーズされた、あるいはビルトインの全てのモジュールを検索する PEP 302 finder を作成します。

ImpImporter は現在のところ sys.meta_path に配置しての利用をサポートしていないことに注意してください。

バージョン 3.3 で非推奨: 標準インポートメカニズムが完全に PEP 302 準拠になり、これが importlib で利用可能であるため、このエミュレーションはもはや必要ありません。

class pkgutil.ImpLoader(fullname, file, filename, etc)

Python の "クラシック" インポートアルゴリズムをラップする loader

バージョン 3.3 で非推奨: 標準インポートメカニズムが完全に PEP 302 準拠になり、これが importlib で利用可能であるため、このエミュレーションはもはや必要ありません。

pkgutil.find_loader(fullname)

fullname に対するモジュール loader オブジェクトを取得します。

これは後方互換性のために提供している importlib.util.find_spec() へのラッパーで、そこでのほどんどの失敗を ImportError に変換し、完全な ModuleSpec を返す代わりにローダのみを返しています。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

バージョン 3.4 で変更: PEP 451 ベースに更新されました。

pkgutil.get_importer(path_item)

指定された path_item に対する finder を取得します。

path hook により新しい finder が作成された場合は、それは sys.path_importer_cache にキャッシュされます。

キャッシュ (やその一部) は、 sys.path_hooks のリスキャンが必要になった場合は手動でクリアすることができます。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.get_loader(module_or_name)

module_or_name に対する loader オブジェクトを取得します。

module か package が通常の import 機構によってアクセスできる場合、その機構の該当部分に対するラッパーを返します。モジュールが見つからなかったり import できない場合は None を返します。その名前のモジュールがまだ import されていない場合、そのモジュールを含むパッケージが(あれば)そのパッケージの __path__ を確立するために import されます。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

バージョン 3.4 で変更: PEP 451 ベースに更新されました。

pkgutil.iter_importers(fullname='')

Yield finder objects for the given module name.

If fullname contains a '.', the finders will be for the package containing fullname, otherwise they will be all registered top level finders (i.e. those on both sys.meta_path and sys.path_hooks).

その名前のついたモジュールがパッケージ内に含まれている場合、この関数を実行した副作用としてそのパッケージが import されます。

モジュール名が指定されない場合は全てのトップレベルの finder が生成されます。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.iter_modules(path=None, prefix='')

Yields ModuleInfo for all submodules on path, or, if path is None, all top-level modules on sys.path.

path は None か、モジュールを検索する path のリストのどちらかでなければなりません。

prefix は出力の全てのモジュール名の頭に出力する文字列です。

注釈

これは iter_modules() メソッドを定義している finder に対してのみ動作します。このインターフェイスは非標準なので、モジュールは importlib.machinery.FileFinder と zipimport.zipimporter の実装も提供します。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

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

path を指定すれば再帰的にその中のモジュールすべてに対して、 path が None ならばアクセスできるすべてのモジュールに対して、ModuleInfo を yield します。

path は None か、モジュールを検索する path のリストのどちらかでなければなりません。

prefix は出力の全てのモジュール名の頭に出力する文字列です。

この関数は与えられた path 上の全ての パッケージ (全てのモジュール ではない) を、サブモジュールを検索するのに必要な __path__ 属性にアクセスするために import します。

onerror は、パッケージを import しようとしたときに何かの例外が発生した場合に、 1つの引数 (import しようとしていたパッケージの名前) で呼び出される関数です。 onerror 関数が提供されない場合、 ImportError は補足され無視されます。それ以外の全ての例外は伝播し、検索を停止させます。

例:

# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

注釈

これは iter_modules() メソッドを定義している finder に対してのみ動作します。このインターフェイスは非標準なので、モジュールは importlib.machinery.FileFinder と zipimport.zipimporter の実装も提供します。

バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に importlib に基くように更新されました。

pkgutil.get_data(package, resource)

パッケージからリソースを取得します。

この関数は loader get_data API のラッパーです。 package 引数は標準的なモジュール形式 (foo.bar) のパッケージ名でなければなりません。 resource 引数は / をパス区切りに使った相対ファイル名の形式です。親ディレクトリを .. としたり、ルートからの (/ で始まる) 名前を使うことはできません。

この関数が返すのは指定されたリソースの内容であるバイナリ文字列です。

ファイルシステム中に位置するパッケージで既にインポートされているものに対しては、次と大体同じです:

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

If the package cannot be located or loaded, or it uses a loader which does not support get_data, then None is returned. In particular, the loader for namespace packages does not support get_data.