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