本文详解为何 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 打包中处理数据文件的推荐路径。
