31.5. pkgutil —パッケージ拡張ユーティリティ—Pythonドキュメント

31.5。 pkgutil —パッケージ拡張ユーティリティ

バージョン2.3の新機能。

ソースコード： ：source： `Lib / pkgutil.py`

---

このモジュールは、インポートシステムのユーティリティ、特にパッケージサポートを提供します。

pkgutil.extend_path(path, name)

パッケージを構成するモジュールの検索パスを拡張します。 使用目的は、パッケージの__init__.pyに次のコードを配置することです。

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

これにより、パッケージの__path__に、パッケージにちなんで名付けられたsys.path上のディレクトリのすべてのサブディレクトリが追加されます。 これは、単一の論理パッケージのさまざまな部分を複数のディレクトリとして配布する場合に役立ちます。

また、*が name 引数と一致する場所から始まる*.pkgファイルも検索します。 この機能は、*.pthファイル（詳細については site モジュールを参照）に似ていますが、importで始まる特殊なケースの行がない点が異なります。 *.pkgファイルは額面どおりに信頼されます。重複のチェックを除いて、*.pkgファイルで見つかったすべてのエントリは、ファイルシステムに存在するかどうかに関係なく、パスに追加されます。 （これは機能です。）

入力パスがリストでない場合（フリーズされたパッケージの場合のように）、変更されずに返されます。 入力パスは変更されません。 拡張コピーが返されます。 アイテムは最後にコピーに追加されるだけです。

sys.path はシーケンスであると想定されています。 既存のディレクトリを参照する（Unicodeまたは8ビット）文字列ではない sys.path の項目は無視されます。 ファイル名として使用するとエラーが発生する sys.path のUnicodeアイテムにより、この関数で例外が発生する場合があります（ os.path.isdir（）の動作に沿って）。

class pkgutil.ImpImporter(dirname=None)

PEP 302 Pythonの「クラシック」インポートアルゴリズムをラップするインポーター。

dirname が文字列の場合、そのディレクトリを検索する PEP 302 インポーターが作成されます。 dirname がNoneの場合、 PEP 302 インポーターが作成され、現在の sys.path に加えてフリーズまたは組み込みのモジュール。

ImpImporter は現在、 sys.meta_path への配置による使用をサポートしていないことに注意してください。

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

PEP 302 Pythonの「クラシック」インポートアルゴリズムをラップするローダー。

pkgutil.find_loader(fullname)

フルネームの PEP 302 「ローダー」オブジェクトを見つけます。

フルネームにドットが含まれている場合、パスは含まれているパッケージの__path__である必要があります。 モジュールが見つからないかインポートできない場合は、Noneを返します。 この関数は iter_importers（）を使用するため、Windowsレジストリなどのプラットフォーム固有の特別なインポート場所に関して同じ制限が適用されます。

pkgutil.get_importer(path_item)

指定された path_item の PEP 302 インポーターを取得します。

返されたインポーターは、パスフックによって新しく作成された場合、 sys.path_importer_cache にキャッシュされます。

インポーターがない場合は、基本的なインポート機構のラッパーが返されます。 このラッパーがインポーターキャッシュに挿入されることはありません（代わりにNoneが挿入されます）。

sys.path_hooks の再スキャンが必要な場合は、キャッシュ（またはその一部）を手動でクリアできます。

pkgutil.get_loader(module_or_name)

module_or_name の PEP 302 「ローダー」オブジェクトを取得します。

モジュールまたはパッケージが通常のインポートメカニズムを介してアクセス可能である場合、その機械の関連部分のラッパーが返されます。 モジュールが見つからないかインポートできない場合は、Noneを返します。 指定されたモジュールがまだインポートされていない場合は、パッケージ__path__を確立するために、そのモジュールを含むパッケージ（存在する場合）がインポートされます。

この関数は iter_importers（）を使用するため、Windowsレジストリなどのプラットフォーム固有の特別なインポート場所に関して同じ制限が適用されます。

pkgutil.iter_importers(fullname=)

指定されたモジュール名の PEP 302 インポーターを生成します。

フルネームに「。」が含まれている場合、インポーターはフルネームを含むパッケージ用になります。それ以外の場合、インポーターは sys.meta_path 、 sys.path 、およびPythonの「クラシック」インポート用になります。機械、この順序で。 指定されたモジュールがパッケージ内にある場合、そのパッケージは、この関数を呼び出すことの副作用としてインポートされます。

非 PEP 302 メカニズム（例： 標準のインポート機構が別の場所にあるファイルを検索するために使用するWindowsレジストリ）は部分的にサポートされていますが、の後に sys.path で検索されます。 通常、これらの場所は before sys.path で検索され、 sys.path エントリがそれらをシャドウイングするのを防ぎます。

これにより動作に目に見える違いが生じるには、 sys.path と PEP 302 [以外のいずれかを介してアクセスできるモジュールまたはパッケージ名が必要です。 X177X]ファイルシステムメカニズム。 この場合、エミュレーションは前者のバージョンを検出し、組み込みのインポートメカニズムは後者を検出します。

次のタイプのアイテムは、この不一致の影響を受ける可能性があります：imp.C_EXTENSION、imp.PY_SOURCE、imp.PY_COMPILED、imp.PKG_DIRECTORY。

pkgutil.iter_modules(path=None, prefix=)

パス上のすべてのサブモジュールに対して(module_loader, name, ispkg)を生成します。パスがNoneの場合は、sys.path上のすべてのトップレベルモジュールを生成します。

path は、Noneまたはでモジュールを検索するパスのリストのいずれかである必要があります。

prefix は、出力時にすべてのモジュール名の前に出力する文字列です。

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

パスですべてのモジュールの(module_loader, name, ispkg)を再帰的に生成します。パスがNoneの場合は、アクセス可能なすべてのモジュールを生成します。

path は、Noneまたはでモジュールを検索するパスのリストのいずれかである必要があります。

prefix は、出力時にすべてのモジュール名の前に出力する文字列です。

この関数は、__path__属性にアクセスするために、指定されたパス上のすべてのパッケージ（ではなくすべてのモジュール！）をインポートする必要があることに注意してください。サブモジュールを見つけます。

onerror は、パッケージのインポート中に例外が発生した場合に、1つの引数（インポートされていたパッケージの名前）で呼び出される関数です。 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の新機能。