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 で追加.