如何构建包含.py与.pyd文件的Python Wheel，实现顶层模块导入

核心问题分析 #

你需要将src下的文件作为顶层模块直接安装到site-packages，而非作为子包。之前的尝试无效是因为：

• 仅设置package-dir但未明确指定要打包的模块列表，setuptools默认只识别.py文件
• packages.find用于识别带__init__.py的包目录，不适用单个模块文件的场景
• package-data配置未配合正确的模块路径定义，无法关联到.pyd文件

正确配置方案 #

1. 修改pyproject.toml

启用模块路径定义、明确指定打包模块，并配置包含.pyd文件：

[build-system]
requires = [
    "setuptools>=64",
    "wheel",
]
build-backend = "setuptools.build_meta"

[project]
name = "my_project"
version = "0.0.1"
authors = [
    { name = "Bobo.The.Clown", email = "bobo@thecircus.com" },
]
description = 'example project'
requires-python = ">=3.9"

[tool.setuptools]
# 将src目录映射为顶层模块的根路径
package-dir = {"" = "src"}
# 明确列出所有要打包的模块（包括.pyd对应的模块名）
py-modules = ["my_module_1", "my_module_2", "my_module_3"]
# 启用package-data的自动包含
include-package-data = true

[tool.setuptools.package-data]
# 为顶层模块（""代表根）包含所有.pyd文件
"" = ["*.pyd"]

2. 调整MANIFEST.in

确保明确包含src下的.py和.pyd文件：

include src/*.py
include src/*.pyd

构建与验证步骤 #

1. 清理旧产物：删除dist/、build/、my_project.egg-info/目录，避免缓存干扰
2. 构建Wheel：在my_project目录执行

   python -m build --wheel
   

3. 安装测试：

   pip install dist/my_project-0.0.1-cp39-none-win_amd64.whl
   

   （注意：实际文件名会根据你的Python版本和平台自动生成）
4. 验证导入：在Python环境中执行

   import my_module_1
   import my_module_2
   import my_module_3
   

   无报错则说明模块已成功安装。

内容的提问来源于stack exchange，提问作者CLR