# 31.2. `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 です。

  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 `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)

  Yields `ModuleInfo` 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`.