pyproject.toml打包数据文件技巧

本文深入剖析了在使用 pyproject.toml 构建 Python 包时，为何将数据文件（如 CSV、JSON）通过 package-data 机制注入单文件模块（py-modules）会彻底失效，并直击根源——package-data 仅对含 __init__.py 的标准 Python 包生效，而非顶层 .py 文件；文章随即给出一套清晰、现代、可落地的解决方案：重构为规范包结构、用 packages 替代 py-modules、配置精准的 package-data 规则，并结合 importlib.resources 安全读取已随包安装至 site-packages 的数据文件，助你告别打包后资源丢失的困扰，真正实现代码与数据的一体化分发。

本文详解为何 package-data 在单文件模块（py-modules）下失效，并提供符合现代 Python 打包规范的解决方案：通过重构为标准包结构 + packages 配置 + 精确的 package-data 规则，确保 my_data/ 中的数据文件随代码一同安装到 site-packages。

本文详解为何 `package-data` 在单文件模块（`py-modules`）下失效，并提供符合现代 Python 打包规范的解决方案：通过重构为标准包结构 + `packages` 配置 + 精确的 `package-data` 规则，确保 `my_data/` 中的数据文件随代码一同安装到 `site-packages`。

在使用 pyproject.toml 进行 Python 包构建时，一个常见误区是：试图用 package-data 机制向单文件模块（即通过 py-modules = ["hello"] 声明的 .py 文件）注入非 Python 数据文件（如 CSV、JSON、配置等）。但根据 setuptools 官方文档，package-data 仅对真正的 Python 包（含 __init__.py 的目录）生效；它不作用于顶层 .py 模块——这正是你执行 pip install . 后 my_data/ 未被复制的根本原因。

✅ 正确做法：采用标准包结构

你需要将当前扁平结构升级为符合 PEP 420 的隐式命名空间包结构：

hello/
├── pyproject.toml
└── hello/                 # ← 新建子目录，作为正式 Python 包
    ├── __init__.py        # ← 必须存在（可为空），标识为包
    ├── my_data.csv        # ← 数据文件直接置于包内（或子目录）
    └── ...                # 其他模块/资源

? 提示：原 hello.py 应重命名为 hello/__init__.py，其内容可保持不变（例如 def hello(): print("Hello, world!")），调用方式仍为 import hello; hello.hello()。

✅ 更新 pyproject.toml 配置

[project]
name = "hello"
version = "0.1"

[tool.setuptools]
# ❌ 移除 py-modules；✅ 改用 packages 自动发现
packages = ["hello"]

[tool.setuptools.package-data]
# "" 表示“所有已声明的包”，匹配 hello/ 下的 *.csv
"" = ["*.csv"]
# 或更精确地指定（推荐）：
# hello = ["my_data.csv"]
# 若需包含子目录（如 hello/my_data/），则写：
# hello = ["my_data/*.csv"]

✅ 验证安装与访问数据

安装后，数据文件将位于 site-packages/hello/my_data.csv。在代码中可通过 importlib.resources（Python ≥3.9）或 importlib_resources（旧版本兼容）安全读取：

# hello/__init__.py
from importlib import resources

def load_data():
    # Python 3.9+
    with resources.files("hello").joinpath("my_data.csv").open("r") as f:
        return f.read()

# Python <3.9（需 pip install importlib-resources）
# from importlib_resources import files
# with files("hello").joinpath("my_data.csv").open("r") as f:
#     ...

⚠️ 注意事项与最佳实践

• 不要依赖 MANIFEST.in：在 pyproject.toml + setuptools 构建体系中，MANIFEST.in 仅影响源码分发（sdist），不影响 wheel 安装或 package-data 行为；此处无需使用。
• 避免将数据复制到任意路径：将 my_data/ 直接复制到 site-packages/ 根目录属于反模式（破坏隔离性），应始终绑定到具体包内。
• 路径匹配区分大小写：*.CSV 不会匹配 my_data.csv（Linux/macOS 默认区分）；建议统一小写并用 *.csv。
• 测试安装前清理缓存：运行 pip install --force-reinstall --no-deps --no-cache-dir . 确保加载最新配置。

遵循以上结构与配置，pip install . 将准确把 my_data.csv 安装至 site-packages/hello/ 目录，并可通过标准资源 API 可靠访问——这才是现代 Python 打包中处理数据文件的推荐路径。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~