importlib.resources -- パッケージリソースの読み取り、オープン、アクセス¶
ソースコード: Lib/importlib/resources/__init__.py
Added in version 3.7.
このモジュールは Python のインポートシステムを利用し、パッケージ 内の リソース にアクセスする機能を提供します。
「リソース」は、Python のモジュールやパッケージに関連付けられた、ファイルに似たものです。
リソースはパッケージの直下やサブディレクトリ内に置くことも、パッケージ外のモジュールの隣に置くこともできます。
テキストの場合もバイナリの場合もあります。
そのため、パッケージの Python モジュールのソース (.py)、コンパイルで生成されるもの (pycache)、インストールで生成されるもの (ディレクトリ内の 予約済みファイル名 など) も、技術的にはそのパッケージの事実上のリソースです。
ただし実際には、リソースとは主に、パッケージの作者が明示的に公開する Python コード以外のものを指します。
リソースはバイナリモードでもテキストモードでも開いたり読み取ったりできます。
リソースはおおむねディレクトリ内のファイルに似ていますが、これは単なる比喩である点に注意してください。
リソースとパッケージは、ファイルシステム上の物理的なファイルやディレクトリとして存在する必要は ありません。
例えば、zipimport を使うとパッケージとそのリソースを zip ファイルからインポートできます。
警告
importlib.resources は組み込みの open() 関数と同じセキュリティモデルに従います。
このモジュールの関数に信頼できない入力を渡すことは安全ではありません。
注釈
このモジュールのスタンドアローンバックポートでは、 importlib.resources の使用 と pkg_resources から importlib.resources への移行 についての詳細情報を提供しています。
Loaders でリソースの読み込みをサポートしたい場合は、 importlib.resources.abc.ResourceReader で指定された get_resource_reader(fullname) メソッドを実装しなければいけません。
- class importlib.resources.Anchor¶
リソースの基点 (アンカー) を表します。
モジュールオブジェクトまたはモジュール名の文字列です。Union[str, ModuleType]として定義されています。
- importlib.resources.files(anchor: Anchor | None = None)¶
リソースのコンテナ (ディレクトリに相当) とそのリソース (ファイルに相当) を表す
Traversableオブジェクトを返します。 Traversable は他のコンテナ (サブディレクトリに相当) を含むこともあります。anchor は省略可能な
Anchorです。 パッケージの場合、リソースはそのパッケージから解決されます。 モジュールの場合は、そのモジュールの隣 (同じパッケージ内またはパッケージのルート) から解決されます。 省略すると呼び出し元のモジュールが使われます。Added in version 3.9.
バージョン 3.12 で変更: package 引数の名前を anchor に変更しました。 package も引き続き受け付けますが、非推奨となりました。
バージョン 3.15 で変更: package parameter was fully removed. anchor can now be a non-package module and if omitted will default to the caller's module. package is no longer accepted since Python 3.15. Consider passing the anchor positionally or using
importlib_resources >= 5.10for a compatible interface on older Pythons.
- importlib.resources.as_file(traversable)¶
通常は
importlib.resources.files()から得られる、ファイルまたはディレクトリを表すTraversableオブジェクトを受け取り、with文で使うコンテキストマネージャを返します。 このコンテキストマネージャはpathlib.Pathオブジェクトを提供します。コンテキストマネージャを抜けると、例えば zip ファイルからリソースを展開する際に作成した一時ファイルや一時ディレクトリを削除します。
Traversable のメソッド (
read_textなど) では足りず、ファイルシステム上の実際のファイルやディレクトリが必要な場合は、as_fileを使ってください。Added in version 3.9.
バージョン 3.12 で変更: ディレクトリを表す traversable をサポートしました。
関数 API¶
簡単に使え、後方互換性のある補助関数が用意されています。 一般的な操作を 1 回の関数呼び出しで行えます。
以下のすべての関数について、次の規則が適用されます。
path_names は、基点からの相対パスとして表したリソースのパス名の構成要素です。 例えば
info.txtというリソースのテキストを取得するには、次のようにします。importlib.resources.read_text(my_module, "info.txt")
Traversable.joinpathと同じく、各構成要素ではパスの区切り文字にスラッシュ (/) を使ってください。 例えば、次の 2 つは等価です。importlib.resources.read_binary(my_module, "pics/painting.png") importlib.resources.read_binary(my_module, "pics", "painting.png")
後方互換性のため、テキストを読む関数に複数の path_names を渡す場合は、encoding 引数を明示する必要があります。 例えば
info/chapter1.txtのテキストを取得するには、次のようにします。importlib.resources.read_text(my_module, "info", "chapter1.txt", encoding='utf-8')
- importlib.resources.open_binary(anchor, *path_names)¶
指定した名前のリソースを、バイナリとして読み取るために開きます。
anchor と path_names の詳細は 冒頭の説明 を参照してください。
この関数は
BinaryIOオブジェクト、つまり読み取り用に開いたバイナリストリームを返します。この関数はおおむね次と等価です。
files(anchor).joinpath(*path_names).open('rb')
バージョン 3.13 で変更: 複数の path_names を指定できるようになりました。
- importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')¶
指定した名前のリソースを、テキストとして読み取るために開きます。 デフォルトでは、内容を厳密な UTF-8 として読み取ります。
anchor と path_names の詳細は 冒頭の説明 を参照してください。 encoding と errors は組み込みの
open()と同じ意味です。For backward compatibility reasons, the encoding argument must be given explicitly if there are multiple path_names. This limitation is scheduled to be removed in Python 3.15.
この関数は
TextIOオブジェクト、つまり読み取り用に開いたテキストストリームを返します。この関数はおおむね次と等価です。
files(anchor).joinpath(*path_names).open('r', encoding=encoding)
バージョン 3.13 で変更: 複数の path_names を指定できるようになりました。 encoding と errors はキーワード引数で指定する必要があります。
- importlib.resources.read_binary(anchor, *path_names)¶
指定した名前のリソースの内容を読み取り、
bytesとして返します。anchor と path_names の詳細は 冒頭の説明 を参照してください。
この関数はおおむね次と等価です。
files(anchor).joinpath(*path_names).read_bytes()
バージョン 3.13 で変更: 複数の path_names を指定できるようになりました。
- importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')¶
指定した名前のリソースの内容を読み取り、
strとして返します。 デフォルトでは、内容を厳密な UTF-8 として読み取ります。anchor と path_names の詳細は 冒頭の説明 を参照してください。 encoding と errors は組み込みの
open()と同じ意味です。For backward compatibility reasons, the encoding argument must be given explicitly if there are multiple path_names. This limitation is scheduled to be removed in Python 3.15.
この関数はおおむね次と等価です。
files(anchor).joinpath(*path_names).read_text(encoding=encoding)
バージョン 3.13 で変更: 複数の path_names を指定できるようになりました。 encoding と errors はキーワード引数で指定する必要があります。
- importlib.resources.path(anchor, *path_names)¶
resource へのパスを、実際のファイルシステムパスとして提供します。 この関数は
with文で使うコンテキストマネージャを返します。 このコンテキストマネージャはpathlib.Pathオブジェクトを提供します。コンテキストマネージャを抜けると、例えば zip ファイルからリソースを展開する際に作成した一時ファイルを削除します。
例えば
stat()メソッドには実際のファイルシステムパスが必要なので、次のように使います。with importlib.resources.path(anchor, "resource.txt") as fspath: result = fspath.stat()
anchor と path_names の詳細は 冒頭の説明 を参照してください。
この関数はおおむね次と等価です。
as_file(files(anchor).joinpath(*path_names))
バージョン 3.13 で変更: 複数の path_names を指定できるようになりました。
- importlib.resources.is_resource(anchor, *path_names)¶
指定した名前のリソースが存在すれば
True、それ以外はFalseを返します。 この関数はディレクトリをリソースとはみなしません。anchor と path_names の詳細は 冒頭の説明 を参照してください。
この関数はおおむね次と等価です。
files(anchor).joinpath(*path_names).is_file()
バージョン 3.13 で変更: 複数の path_names を指定できるようになりました。
- importlib.resources.contents(anchor, *path_names)¶
パッケージまたはパス内の項目の名前を返すイテラブルを返します。 このイテラブルは、リソース (ファイルなど) とリソース以外のもの (ディレクトリなど) の名前を
strで返します。 サブディレクトリ内を再帰的にたどることはありません。anchor と path_names の詳細は 冒頭の説明 を参照してください。
この関数はおおむね次と等価です。
for resource in files(anchor).joinpath(*path_names).iterdir(): yield resource.name
バージョン 3.11 で非推奨: 上記の
iterdir()を優先して使ってください。 結果をより細かく制御でき、機能も豊富です。