31.5. "pkgutil" --- パッケージ拡張ユーティリティ
************************************************

バージョン 2.3 で追加.

**ソースコード:** 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"
   の要素の内、実在するディレクトリを指す (Unicode または 8 ビットの)
   文字列となっていないものは無視されます。ファイル名として使ったとき
   にエラーが発生する "sys.path" の Unicode 要素がある場合、この関数
   ("os.path.isdir()" を実行している行) で例外が発生する可能性がありま
   す。

class pkgutil.ImpImporter(dirname=None)

   Python の "クラシック" インポートアルゴリズムをラップする **PEP
   302** Importer.

   *dirname* が文字列の場合、そのディレクトリを検索する **PEP 302**
   importer を作成します。 *dirname* が "None" のとき、現在の
   "sys.path" とフリーズされた、あるいはビルトインの全てのモジュールを
   検索する **PEP 302** importer を作成します。

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

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

   Python の "クラシック" インポートアルゴリズムをラップする **PEP
   302** Loader.

pkgutil.find_loader(fullname)

   *fullname* に対する **PEP 302** "loader" オブジェクトを検索します。

   *fullname* にドットが含まれる場合、パスはそれを包含しているパッケー
   ジの "__path__" のはずです。モジュールが見つからない場合や import
   できない場合は "None" を返します。この関数は "iter_importers()" を
   利用しているので、それと同じように、 Windows レジストリなどのプラッ
   トフォーム依存の特別な import 場所に関する制限があります。

pkgutil.get_importer(path_item)

   指定された *path_item* に対する **PEP 302** importer を取得します。

   path hook により新しい importer が作成された場合は、それは
   "sys.path_importer_cache" にキャッシュされます。

   importer が存在しない場合、基本 import 機構のラッパーを返します。こ
   のラッパーは importer cache にはキャッシュされません (代わりに
   "None" が insert されます)。

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

pkgutil.get_loader(module_or_name)

   *module_or_name* に対する **PEP 302** "loader" を取得します。

   module か package が通常の import 機構によってアクセスできる場合、
   その機構の該当部分に対するラッパーを返します。モジュールが見つから
   なかったり import できない場合は "None" を返します。その名前のモジ
   ュールがまだ import されていない場合、そのモジュールを含むパッケー
   ジが(あれば)そのパッケージの "__path__" を確立するために import さ
   れます。

   この関数は "iter_importers()" を利用しているので、それと同じように
   、 Windows レジストリなどのプラットフォーム依存の特別な import 場所
   に関する制限があります。

pkgutil.iter_importers(fullname='')

   指定された名前に対する **PEP 302** importer を yield します (---訳
   注: 原文は the given module name になっていますが、(わかりやすいか
   もしれませんが) 厳密にはこれは間違い。 fullname に "cc" や
   "aa.bb.cc" を渡した場合の "cc" はモジュールでもパッケージでもよく、
   いずれにせよそれを含む親パッケージの importer が返ります。---)。

   *fullname* が '.' を含む場合、返されるのは fullname を包含するパッ
   ケージの importer になり (---訳注: "fullname="aaa.bbb.ccc"" の場合
   ""aaa.bbb"" の importer。---)、それ以外の場合は "sys.meta_path",
   "sys.path", そして Python の "クラシック" import 機構の順のどれかの
   importer になります。その名前のついたモジュールがパッケージ内に含ま
   れている場合、この関数を実行した副作用としてそのパッケージが import
   されます。

   標準の import 機構がファイルを別の場所から探す、 **PEP 302** 以外の
   機構 (例: Windows レジストリ) はある程度までサポートされていますが
   、それは "sys.path" の *後に* 検索されます。通常はそれらの場所は、
   "sys.path" のエントリに隠されないように "sys.path" の *前に* 検索さ
   れます。

   モジュールやパッケージ名が "sys.path" と非 **PEP 302** のファイルシ
   ステム機構のどちらからもアクセスできると、このことは目に見える振る
   舞いの違いをもたらします。この場合、エミュレート時は前者から、ビル
   トインの import 機構は後者からモジュールやパッケージを見つけます。

   この動作の食い違いにより、以下の種類の要素が影響を受けるかもしれま
   せん: "imp.C_EXTENSION", "imp.PY_SOURCE", "imp.PY_COMPILED",
   "imp.PKG_DIRECTORY".

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

   *path* を指定すればその全てのサブモジュールに対して、 *path* が
   "None" なら "sys.path" の全てのトップレベルモジュールに対して、
   "(module_loader, name, ispkg)" のタプルを yield します。

   *path* は "None" か、モジュールを検索する path のリストのどちらかで
   なければなりません。

   *prefix* は出力の全てのモジュール名の頭に出力する文字列です。

pkgutil.walk_packages(path=None, prefix='', onerror=None)

   *path* を指定すれば再帰的にその中のモジュール全てに対して、 *path*
   が "None" ならばアクセスできる全てのモジュールに対して、
   "(module_loader, name, ispkg)" のタプルを 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__ + '.')

pkgutil.get_data(package, resource)

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

   この関数は **PEP 302** ローダーの "get_data()" API のラッパーです。
   *package* 引数は標準的なモジュール形式 ("foo.bar") のパッケージ名で
   なければなりません。 *resource* 引数は "/" をパス区切りに使った相対
   ファイル名の形式です。親ディレクトリを ".." としたり、ルートからの
   ("/" で始まる) 名前を使うことはできません。

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

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

      d = os.path.dirname(sys.modules[package].__file__)
      data = open(os.path.join(d, resource), 'rb').read()

   パッケージを見出せなかったりロードできなかったり、あるいは
   "get_data()" をサポートしない **PEP 302** ローダーを使ったりした場
   合は、 "None" が返されます。

   バージョン 2.6 で追加.
