Python importlib.resources Traversable 怎么读取包内目录

读取 Python 包内目录，推荐从 importlib.resources.files() 开始：它返回一个表示资源容器的 Traversable。用 joinpath() 进入子目录，用 iterdir() 枚举成员，再通过 is_file()、is_dir()、read_text() 或 read_bytes() 处理具体资源。不要先把它强制当成 pathlib.Path，因为包可能来自 zip 文件，资源并不一定有永久的真实路径。

官方文档：https://docs.python.org/3.14/library/importlib.resources.html

从包资源根目录开始，而不是拼接 __file__

假设要读取的包结构如下。资源目录和文件必须实际包含在最终安装包中：

demo_pkg/
├── __init__.py
└── templates/          # 包内资源目录
    ├── welcome.txt     # 文本模板
    └── error.txt       # 错误提示模板

files() 的参数叫 anchor，可以传包对象、模块对象或模块名字符串。若传入包名，资源就从该包的根容器解析：

from importlib.resources import files

# 取得包资源根容器；返回值只承诺 Traversable 接口。
package_root = files("demo_pkg")
templates = package_root.joinpath("templates")

if not templates.is_dir():
    # 安装后找不到目录时，优先检查资源是否被打进 wheel。
    raise FileNotFoundError("demo_pkg/templates 未随包安装")

这里的 templates 仍然是 Traversable。它看起来像目录，但不保证是磁盘上的普通目录。这个抽象正是 importlib.resources 能兼容文件系统包和 zipimport 包的关键。

用 iterdir 遍历目录并读取文件

Traversable.iterdir() 会产出当前容器中的子 Traversable。它默认不递归，因此可以先按名称排序，再根据类型决定读取还是继续进入子目录：

from importlib.resources import files

templates = files("demo_pkg").joinpath("templates")

# 按资源名排序，让处理结果在不同加载器下更稳定。
for item in sorted(templates.iterdir(), key=lambda entry: entry.name):
    if item.is_file() and item.name.endswith(".txt"):
        # 文本资源显式指定编码，避免依赖本机默认编码。
        text = item.read_text(encoding="utf-8")
        print(item.name, len(text))
    elif item.is_dir():
        # 子目录仍是 Traversable，可继续调用 iterdir()。
        print("子目录：", item.name)

如果只想读取一个已知文件，不必遍历整个目录：

from importlib.resources import files

welcome = (
    files("demo_pkg")
    .joinpath("templates")
    .joinpath("welcome.txt")
)

if not welcome.is_file():
    # Traversable 没有要求提供 exists()，用类型判断确认资源。
    raise FileNotFoundError("welcome.txt 不存在")

content = welcome.read_text(encoding="utf-8")
print(content)

需要递归读取时，让 Traversable 一直保持抽象

有些包会在资源目录下继续分语言或主题。递归函数只依赖 iterdir()、is_dir() 和 is_file()，就不需要知道资源来自普通目录还是压缩包：

from importlib.resources import files
from importlib.resources.abc import Traversable

def walk_text_files(node: Traversable, prefix: str = ""):
    # 递归产出相对名称和对应 Traversable，不泄漏临时路径。
    for child in sorted(node.iterdir(), key=lambda entry: entry.name):
        relative = f"{prefix}/{child.name}" if prefix else child.name
        if child.is_dir():
            yield from walk_text_files(child, relative)
        elif child.is_file() and child.name.endswith(".txt"):
            yield relative, child

root = files("demo_pkg").joinpath("templates")
for relative_name, resource in walk_text_files(root):
    # 每个文件仍通过资源接口读取，兼容非文件系统加载器。
    text = resource.read_text(encoding="utf-8")
    print(relative_name, len(text))

只有外部库要求真实目录时才使用 as_file

某些第三方库只接受 pathlib.Path 或文件系统目录，这时才把 Traversable 交给 as_file()。Python 3.12 起，as_file() 支持目录；如果资源位于 zip 包中，它可能临时解压目录，并在退出 with 后清理。

from importlib.resources import as_file, files

templates = files("demo_pkg").joinpath("templates")

with as_file(templates) as real_directory:
    # 真实目录只在上下文内有效，外部库应在这里完成读取。
    print(real_directory)
    assert real_directory.is_dir()

# 不要把 real_directory 保存后在 with 外继续使用。

不要把 str(traversable) 当作真实路径，也不要从对象内部属性猜测磁盘位置。只要业务能用 read_text()、read_bytes() 或 open() 完成，就没有必要产生临时目录。

从旧接口迁移时要注意的版本变化

如果项目同时支持较旧 Python，可以采用独立的 importlib_resources 回移包。官方文档建议需要兼容新式 anchor 接口时使用 importlib_resources >= 5.10。但无论使用标准库还是回移包，业务代码都应围绕 Traversable 编写，而不是重新退回 __file__ 拼路径。

安装后读取失败怎么检查

1. 先确认 files("demo_pkg") 的 anchor 指向正确包，而不是同名脚本或错误模块；
2. 再检查 templates.is_dir()，区分目录缺失和文件读取异常；
3. 确认资源已包含在 wheel 或其他分发产物中，不能只看源码目录；
4. 若资源来自 zip 包，不要假设它有永久真实路径；
5. 如果使用 as_file()，确认所有读取都发生在上下文退出之前；
6. 文本资源显式传 encoding="utf-8"，二进制资源改用 read_bytes()。

常见问题

Traversable 和 pathlib.Path 有什么区别？

Traversable 只提供遍历、判断和读取资源所需的一小组路径式接口，背后可以不是文件系统；pathlib.Path 明确表示真实文件系统路径。需要后者时使用 as_file()。

iterdir 会递归列出全部文件吗？

不会。它只枚举当前容器的直接成员；需要递归时，对 is_dir() 为真的成员继续调用 iterdir()。

为什么源码目录能读，安装 wheel 后却找不到？

最常见原因是资源没有被打进分发产物。importlib.resources 只能读取加载器公开的已安装资源，不能自动把源码目录中的任意文件加入 wheel。

可以把 as_file 返回的目录缓存起来吗？

不能假设它在上下文外仍有效。对于 zip 资源，目录可能是临时提取结果；需要长期使用时，应在上下文内复制到由应用自己管理的位置。