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".
