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

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

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

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 です。

If dirname is a string, a PEP 302 finder is created that searches that directory. If dirname is None, a PEP 302 finder is created that searches the current sys.path, plus any modules that are frozen or built-in.

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

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

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

Loader that wraps Python's "classic" import algorithm.

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

pkgutil.find_loader(fullname)

Retrieve a module loader for the given fullname.

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

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

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

pkgutil.get_importer(path_item)

Retrieve a finder for the given path_item.

The returned finder is cached in sys.path_importer_cache if it was newly created by a path hook.

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

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

pkgutil.get_loader(module_or_name)

Get a loader object for module_or_name.

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 されます。

If no module name is specified, all top level finders are produced.

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

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

Yields (module_finder, name, ispkg) 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)

Yields (module_finder, name, ispkg) for all modules recursively on path, or, if path is None, all accessible modules.

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)

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

This is a wrapper for the loader get_data API. The package argument should be the name of a package, in standard module format (foo.bar). The resource argument should be in the form of a relative filename, using / as the path separator. The parent directory name .. is not allowed, and nor is a rooted name (starting with a /).

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

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

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.