31.2. 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 です。
If dirname is a string, a PEP 302 finder is created that searches that directory. If dirname is
None
, a PEP 302 finder is created that searches the currentsys.path
, plus any modules that are frozen or built-in.ImpImporter
は現在のところsys.meta_path
に配置しての利用をサポートしていないことに注意してください。バージョン 3.3 で撤廃: 標準インポートメカニズムが完全に PEP 302 準拠になり、これが
importlib
で利用可能であるため、このエミュレーションはもはや必要ありません。
-
class
pkgutil.
ImpLoader
(fullname, file, filename, etc)¶ Loader that wraps Python’s "classic" import algorithm.
バージョン 3.3 で撤廃: 標準インポートメカニズムが完全に PEP 302 準拠になり、これが
importlib
で利用可能であるため、このエミュレーションはもはや必要ありません。
-
pkgutil.
find_loader
(fullname)¶ Retrieve a module loader for the given fullname.
これは後方互換性のために提供している
importlib.util.find_spec()
へのラッパーで、そこでのほどんどの失敗をImportError
に変換し、完全なModuleSpec
を返す代わりにローダのみを返しています。バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に
importlib
に基くように更新されました。バージョン 3.4 で変更: PEP 451 ベースに更新されました。
-
pkgutil.
get_importer
(path_item)¶ Retrieve a finder for the given path_item.
The returned finder is cached in
sys.path_importer_cache
if it was newly created by a path hook.キャッシュ (やその一部) は、
sys.path_hooks
のリスキャンが必要になった場合は手動でクリアすることができます。バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に
importlib
に基くように更新されました。
-
pkgutil.
get_loader
(module_or_name)¶ Get a loader object for module_or_name.
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 されます。
If no module name is specified, all top level finders are produced.
バージョン 3.3 で変更: パッケージ内部の PEP 302 エミュレーションに依存するのではなく直接的に
importlib
に基くように更新されました。
-
pkgutil.
iter_modules
(path=None, prefix='')¶ Yields
ModuleInfo
for all submodules on path, or, if path isNone
, all top-level modules onsys.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)¶ Yields
ModuleInfo
for all modules recursively on path, or, if path isNone
, all accessible modules.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)¶ パッケージからリソースを取得します。
This is a wrapper for the loader
get_data
API. The package argument should be the name of a package, in standard module format (foo.bar
). The resource argument should be in the form of a relative filename, using/
as the path separator. The parent directory name..
is not allowed, and nor is a rooted name (starting with a/
).この関数が返すのは指定されたリソースの内容であるバイナリ文字列です。
ファイルシステム中に位置するパッケージで既にインポートされているものに対しては、次と大体同じです:
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
, thenNone
is returned. In particular, the loader for namespace packages does not supportget_data
.