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.find_loader(fullname)¶
Retrieve a module loader for the given fullname.
This is a backwards compatibility wrapper around
importlib.util.find_spec()that converts most failures toImportErrorand only returns the loader rather than the fullimportlib.machinery.ModuleSpec.バージョン 3.4 で変更: Updated to be based on PEP 451
Deprecated since version 3.12, will be removed in version 3.14: Use
importlib.util.find_spec()instead.
- pkgutil.get_importer(path_item)¶
指定された path_item に対する finder を取得します。
path hook により新しい finder が作成された場合は、それは
sys.path_importer_cacheにキャッシュされます。キャッシュ (やその一部) は、
sys.path_hooksのリスキャンが必要になった場合は手動でクリアすることができます。
- pkgutil.get_loader(module_or_name)¶
Get a loader object for module_or_name.
If the module or package is accessible via the normal import mechanism, a wrapper around the relevant part of that machinery is returned. Returns
Noneif the module cannot be found or imported. If the named module is not already imported, its containing package (if any) is imported, in order to establish the package__path__.バージョン 3.4 で変更: Updated to be based on PEP 451
Deprecated since version 3.12, will be removed in version 3.14: Use
importlib.util.find_spec()instead.
- pkgutil.iter_importers(fullname='')¶
指定されたモジュール名に対応する finder オブジェクトを yield します。
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 bothsys.meta_pathandsys.path_hooks).その名前のついたモジュールがパッケージ内に含まれている場合、この関数を実行した副作用としてそのパッケージが import されます。
モジュール名が指定されない場合は全てのトップレベルの finder が生成されます。
- 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の実装も提供します。
- 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の実装も提供します。
- pkgutil.get_data(package, resource)¶
パッケージからリソースを取得します。
This is a wrapper for the loader
get_dataAPI. 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.この関数が返すのは指定されたリソースの内容であるバイナリ文字列です。
This function uses the loader method
get_data()to support modules installed in the filesystem, but also in zip files, databases, or elsewhere.ファイルシステム中に位置するパッケージで既にインポートされているものに対しては、次と大体同じです:
d = os.path.dirname(sys.modules[package].__file__) data = open(os.path.join(d, resource), 'rb').read()
Like the
open()function,get_data()can follow parent directories (../) and absolute paths (starting with/orC:/, for example). It can open compilation/installation artifacts like.pyand.pycfiles or files withreserved filenames. To be compatible with non-filesystem loaders, avoid using these features.警告
This function is intended for trusted input. It does not verify that resource "belongs" to package.
If you use a user-provided resource path, consider verifying it. For example, require an alphanumeric filename with a known extension, or install and check a list of known resources.
パッケージが見つからないか読み込めない場合、またはパッケージが使う loader が
get_dataをサポートしていない場合は、Noneを返します。 特に、名前空間パッケージ の loader はget_dataをサポートしていません。参考
The
importlib.resourcesmodule provides structured access to module resources.
- pkgutil.resolve_name(name)¶
名前をオブジェクトに解決します。
この機能は標準ライブラリのさまざまな場所で使われています (bpo-12915 を参照)。 setuptools、Django、Pyramid のような広く使われているサードパーティーのパッケージにも、同等の機能があります。
name には以下のいずれかの形式の文字列を指定します。 これらの擬似正規表現では、W は有効な Python 識別子を表し、ドットは文字としてのピリオドを表します:
W(.W)*W(.W)*:(W(.W)*)?
最初の形式は後方互換性のためだけのものです。 ドットで区切られた名前の一部がパッケージで、残りはそのパッケージ内のオブジェクトを指すとみなします。 そのオブジェクトが他のオブジェクトの中にネストしている場合もあります。 名前を見るだけでは、どこまでがパッケージで、どこからオブジェクトの階層が始まるか判別できないため、この形式ではインポートを繰り返し試みる必要があります。
2 番目の形式では、呼び出し側がコロンを 1 つ挿入して境界を明示します。 コロンの左側のドット区切りの名前はインポートするパッケージ、右側のドット区切りの名前はそのパッケージ内のオブジェクトの階層です。 この形式ではインポートが 1 回で済みます。 コロンで終わる場合はモジュールオブジェクトを返します。
この関数はオブジェクト (モジュールの場合もあります) を返すか、次のいずれかの例外を送出します:
ValueError-- name が認識可能な形式でない場合。ImportError-- 成功するはずのインポートが失敗した場合。AttributeError-- 目的のオブジェクトを取得するために、インポートしたパッケージ内のオブジェクトの階層をたどる途中で失敗した場合。Added in version 3.9.