importlib.resources – 包資源讀取、開啟和訪問¶
原始碼: Lib/importlib/resources/__init__.py
在 3.7 版本中新增。
此模組利用 Python 的匯入系統來提供對包內資源的訪問。
“資源”是與 Python 中的模組或包關聯的類檔案資源。資源可以直接包含在包中，包含在該包內的子目錄中，或與包外的模組相鄰。資源可以是文字或二進位制檔案。因此，包的 Python 模組源 (.py) 和編譯工件 (pycache) 在技術上是該包的事實資源。然而，在實踐中，資源主要是由包作者專門公開的非 Python 工件。
資源可以在二進位制或文字模式下開啟或讀取。
資源大致類似於目錄內的檔案，但重要的是要記住這只是一種比喻。資源和包不必作為檔案系統上的物理檔案和目錄存在：例如，可以使用 zipimport 從 zip 檔案匯入包及其資源。
注意
此模組提供的功能類似於 pkg_resources 基本資源訪問，而沒有該包的效能開銷。這使得讀取包中包含的資源更容易，具有更穩定和一致的語義。
此模組的獨立反向移植提供了有關 使用 importlib.resources 和 從 pkg_resources 遷移到 importlib.resources 的更多資訊。
希望支援資源讀取的 載入器 應該實現 importlib.resources.abc.ResourceReader 指定的 get_resource_reader(fullname) 方法。
- importlib.resources.files(anchor: Anchor | None = None)¶
返回一個
Traversable物件，該物件表示資源容器（可以認為是目錄）及其資源（可以認為是檔案）。Traversable 可能包含其他容器（可以認為是子目錄）。anchor 是一個可選的
Anchor。如果 anchor 是一個包，則從該包解析資源。如果是一個模組，則在模組旁邊（在同一個包或包根中）解析資源。如果省略 anchor，則使用呼叫者的模組。在 3.9 版本中新增。
在 3.12 版本中更改: package 引數已重新命名為 anchor。anchor 現在可以是非包模組，如果省略則預設為呼叫者的模組。為了相容性，仍然接受 package，但會引發
DeprecationWarning。考慮按位置傳遞 anchor 或對舊版 Python 使用importlib_resources >= 5.10以獲得相容的介面。
- importlib.resources.as_file(traversable)¶
給定一個表示檔案或目錄的
Traversable物件，通常來自importlib.resources.files()，返回一個上下文管理器，用於with語句中。上下文管理器提供一個pathlib.Path物件。退出上下文管理器會清理從 zip 檔案等提取資源時建立的任何臨時檔案或目錄。
當 Traversable 方法（
read_text等）不足並且需要檔案系統上的實際檔案或目錄時，請使用as_file。在 3.9 版本中新增。
在 3.12 版本中更改: 添加了對錶示目錄的 traversable 的支援。
函式式 API¶
提供了一組簡化的、向後相容的幫助程式。這些允許在單個函式呼叫中執行常見操作。
對於以下所有函式
path_names 是相對於 anchor 的資源路徑名稱的組成部分。例如，要獲取名為
info.txt的資源的文字，請使用importlib.resources.read_text(my_module, "info.txt")
與
Traversable.joinpath類似，各個組成部分應使用正斜槓 (/) 作為路徑分隔符。例如，以下是等效的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()相同。出於向後相容的原因，如果存在多個path_names，則必須顯式給出encoding引數。此限制計劃在 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()相同。出於向後相容的原因，如果存在多個path_names，則必須顯式給出encoding引數。此限制計劃在 Python 3.15 中移除。
此函式大致等效於
files(anchor).joinpath(*path_names).read_text(encoding=encoding)
3.13 版本更改: 接受多個path_names。encoding和errors必須作為關鍵字引數給出。
- importlib.resources.path(anchor, *path_names)¶
提供作為實際檔案系統路徑的資源的路徑。此函式返回一個上下文管理器，用於
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。encoding和errors必須作為關鍵字引數給出。
- 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()，它可以提供對結果的更多控制和更豐富的功能。