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

**ソースコード:** Lib/pkgutil.py

======================================================================

このモジュールはインポートシステムの、特にパッケージサポートに関するユ
ーティリティです。

class pkgutil.ModuleInfo(module_finder, name, ispkg)

   モジュールの概要情報を格納する namedtuple

   Added in version 3.6.

pkgutil.extend_path(path, name)

   パッケージを構成するモジュールの検索パスを拡張します。パッケージの
   "__init__.py" で次のように書くことを意図したものです:

      from pkgutil import extend_path
      __path__ = extend_path(__path__, __name__)

   "sys.path" に含まれる各ディレクトリについて、パッケージ名と一致する
   サブディレクトリがあれば、それをパッケージの "__path__" に追加しま
   す。 論理的には 1 つのパッケージを、複数のディレクトリに分けて配布
   したい場合に便利です。

   "*" が *name* 引数に一致する "*.pkg" ファイルも探します。 この機能
   は "*.pth" ファイルと似ていますが (詳しくは "site" モジュールを参照
   )、"import" で始まる行を特別扱いしない点が異なります。 "*.pkg" ファ
   イルの内容はそのまま信頼されます。 空行とコメントを無視する以外は、
   ファイルシステム上に存在するかどうかにかかわらず、"*.pkg" ファイル
   内のすべてのエントリをパスに追加します (これは仕様です)。

   入力パスがリストでない場合 (凍結されたパッケージなど) は、そのまま
   返します。 入力パスは変更せず、拡張したコピーを返します。 要素の追
   加はコピーの末尾にのみ行います。

   "sys.path" はシーケンスであることを前提とします。 "sys.path" の要素
   のうち、既存のディレクトリを指す文字列でないものは無視します。
   "sys.path" に、ファイル名として使うとエラーになる Unicode 要素があ
   る場合、この関数は例外を送出することがあります ("os.path.isdir()"
   の動作に準じます)。

pkgutil.get_importer(path_item)

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

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

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

   バージョン 3.3 で変更: パッケージ内部の **PEP 302** エミュレーショ
   ンに依存するのではなく直接的に "importlib" に基くように更新されまし
   た。

pkgutil.iter_importers(fullname='')

   指定されたモジュール名に対応する *finder* オブジェクトを yield しま
   す。

   *fullname* に "'.'" が含まれる場合は、*fullname* を含むパッケージに
   対する finder を返します。 それ以外の場合は、登録されているすべての
   トップレベルの finder (つまり "sys.meta_path" に登録されたものと、
   "sys.path_hooks" 経由で得られるもの) を返します。

   その名前のついたモジュールがパッケージ内に含まれている場合、この関
   数を実行した副作用としてそのパッケージが import されます。

   モジュール名が指定されない場合は全てのトップレベルの finder が生成
   されます。

   バージョン 3.3 で変更: パッケージ内部の **PEP 302** エミュレーショ
   ンに依存するのではなく直接的に "importlib" に基くように更新されまし
   た。

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

   *path* を指定すればそのすべてのサブモジュールに対して、 *path* が
   "None" なら "sys.path" のすべてのトップレベルモジュールに対して、
   "ModuleInfo" を yield します。

   *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" は補足され無視されます。それ以外の全ての例外は伝播し
   、検索を停止させます。

   例:

      # Python からアクセスできるすべてのモジュールを列挙する
      walk_packages()

      # 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* 引数には、パスの区切り文字として "/" を使う相対ファ
   イル名を指定します。

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

   この関数は *loader* の "get_data()" メソッドを使うことで、ファイル
   システムだけでなく、zip ファイル、データベース、その他の場所にイン
   ストールされたモジュールにも対応します。

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

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

   "open()" 関数と同様に、"get_data()" は親ディレクトリ ("../") や絶対
   パス (例えば "/" や "C:/" で始まるもの) をたどれます。 ".py" や
   ".pyc" ファイルのようなコンパイル・インストール時の生成物や、"予約
   済みのファイル名" を持つファイルも開けます。 ファイルシステム以外の
   ローダーとの互換性を保つには、これらの機能を使わないでください。

   警告:

     この関数は信頼できる入力を対象としています。 *resource* が
     *package* に「属する」ことは検証しません。

   ユーザーが指定した *resource* パスを使う場合は、検証することを検討
   してください。 例えば、既知の拡張子を持つ英数字のファイル名だけを認
   めるか、既知のリソースのリストをインストールして照合します。

   パッケージが見つからないか読み込めない場合、またはパッケージが使う
   *loader* が "get_data" をサポートしていない場合は、"None" を返しま
   す。 特に、*名前空間パッケージ* の *loader* は "get_data" をサポー
   トしていません。

   参考:

     "importlib.resources" モジュールは、モジュールのリソースに構造化
     された方法でアクセスする機能を提供します。

pkgutil.resolve_name(name, *, strict=False)

   名前をオブジェクトに解決します。

   この機能は標準ライブラリのさまざまな場所で使われています (bpo-12915
   を参照)。 setuptools、Django、Pyramid のような広く使われているサー
   ドパーティーのパッケージにも、同等の機能があります。

   *name* には以下のいずれかの形式の文字列を指定します。 これらの擬似
   正規表現では、W は有効な Python 識別子を表し、ドットは文字としての
   ピリオドを表します:

   * "W(.W)*"

   * "W(.W)*:(W(.W)*)?"

   * "W(.W)*:(W(.W)*)"

   最初の形式は後方互換性のためだけのものです。 ドットで区切られた名前
   の一部がパッケージで、残りはそのパッケージ内のオブジェクトを指すと
   みなします。 そのオブジェクトが他のオブジェクトの中にネストしている
   場合もあります。 名前を見るだけでは、どこまでがパッケージで、どこか
   らオブジェクトの階層が始まるか判別できないため、この形式ではインポ
   ートを繰り返し試みる必要があります。

   2 番目の形式では、呼び出し側がコロンを 1 つ挿入して境界を明示します
   。 コロンの左側のドット区切りの名前はインポートするパッケージ、右側
   のドット区切りの名前はそのパッケージ内のオブジェクトの階層です。 こ
   の形式ではインポートが 1 回で済みます。 コロンで終わる場合はモジュ
   ールオブジェクトを返します。

   "strict=False" (デフォルト) の場合は最初の 2 つの形式を受け付けます
   。

   The third form requires both the module name and callable,
   separated by a colon. Only this form is accepted when
   "strict=True".

   この関数はオブジェクト (モジュールの場合もあります) を返すか、次の
   いずれかの例外を送出します:

   "ValueError" -- *name* が認識可能な形式でない場合。

   "ImportError" -- 成功するはずのインポートが失敗した場合。

   "AttributeError" -- 目的のオブジェクトを取得するために、インポート
   したパッケージ内のオブジェクトの階層をたどる途中で失敗した場合。

   Added in version 3.9.

   バージョン 3.15 で変更: 省略可能なキーワード専用フラグ "strict" が
   追加されました。
