（Wheel 格式） Python 的标准分发格式的生成规则规范

.whl 文件（Wheel 格式）是 Python 的标准分发格式，其生成规则主要遵循以下规范：

---

1. 文件名命名规则

.whl 文件名格式为：

{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl

例如：numpy-1.22.3-cp39-cp39-win_amd64.whl

• distribution ：包名（如 numpy）
• version ：版本号（如 1.22.3）
• build tag（可选）：构建编号（通常省略）
• python tag ：支持的 Python 版本（如 cp39 表示 CPython 3.9）
• abi tag ：ABI 兼容性标记（如 none、cp39）
• platform tag ：平台标记（如 win_amd64、linux_x86_64、any）

---

2. 核心生成规则

（1）依赖工具

必须安装 setuptools 和 wheel：

pip install setuptools wheel

（2）项目结构要求

my_package/
├── setup.py          # 必须
├── pyproject.toml    # （可选，现代项目推荐）
└── my_package/       # 包目录
    ├── __init__.py   # 必须（标识为 Python 包）
    └── module.py     # 你的代码

（3）setup.py 关键配置

from setuptools import setup

setup(
    name="my_package",       # 包名（必须）
    version="0.1",           # 版本号（必须）
    packages=["my_package"], # 包含的包（或使用 find_packages()）
    python_requires=">=3.6", # Python 版本要求（可选）
    install_requires=[],     # 依赖项（可选）
)

（4）生成命令

python setup.py bdist_wheel  # 生成 whl 文件到 dist/ 目录

或使用现代构建工具：

pip install build
python -m build --wheel      # 推荐方式（需 pyproject.toml）

---

3. 平台与兼容性标记

• 纯 Python 包 ：标记为 py3-none-any.whl
  （适用于所有 Python 版本和平台）
• 平台特定包 ：如 cp39-cp39-win_amd64.whl
  （需编译 C 扩展，依赖特定 Python 版本和操作系统）

---

4. pyproject.toml（现代项目推荐）

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

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

---

5. 验证生成的 whl

检查文件内容：

unzip -l dist/my_package-0.1-py3-none-any.whl

应包含：

• 包代码（如 my_package/__init__.py）
• 元数据（如 *.dist-info/ 目录）

---

6. 注意事项

1. 避免顶层代码 ：setup.py 中不应有业务逻辑，仅用于配置。
2. 版本号规范 ：遵循 PEP 440（如 1.0.0、2.1.0rc1）。
3. 跨平台 ：纯 Python 包用 any 标记，C 扩展需分平台编译。

---

通过以上规则，可以生成符合标准的 .whl 文件，并通过 pip install 分发或安装。