# `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`.