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のリスキャンが必要になった場合は手動でクリアすることができます。
- pkgutil.iter_importers(fullname='')¶
指定されたモジュール名に対応する finder オブジェクトを yield します。
fullname に
'.'が含まれる場合は、fullname を含むパッケージに対する finder を返します。 それ以外の場合は、登録されているすべてのトップレベルの finder (つまりsys.meta_pathに登録されたものと、sys.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)¶
パッケージからリソースを取得します。
これは loader の
get_dataAPI のラッパーです。 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が追加されました。