Python 教程 / 创建包并验证 wheel 安装
Python 项目可以在 pyproject.toml 中声明项目与构建信息,再生成 wheel 等分发文件。应把构建结果安装到干净环境,并在源码目录之外验证导入和命令,才能发现只在开发文件夹中偶然成功的问题。
区分分发名称、导入包与布局
本地分发名称是 expensekit-demo,Python 导入包是 expensekit。分发名可含连字符,并不要求与模块名完全相同;生成文件名中的下划线也可能来自名称规范化,不要为表面一致而随意改名。
src 布局把包放进 src/expensekit,减少项目根目录直接导入源码而掩盖安装遗漏的情况。构建流程见Python Packaging 官方教程。请使用 Python 3.12 以上与独立练习目录,环境选择可参考虚拟环境与 pip。
这里的名称仅供本地练习,不表示已经取得公共仓库名称的使用权。本文验证本地构建与安装,不执行公共包仓库上传。
创建项目的全部源文件
新建 project 目录,在其中创建 src/expensekit。把下面内容以 UTF-8 保存为 src/expensekit/__init__.py:
def total(amounts):
if any(type(x) is not int or x < 0 for x in amounts):
raise ValueError("invalid amount")
return sum(amounts)
此函数接收可以重复遍历的整数序列,拒绝负数、bool 和字符串,空列表返回 0。它先 any 再 sum,所以不能把一次性迭代器视为同样受支持的输入;生成器可能在检查后已耗尽。
同目录创建 src/expensekit/cli.py:
import argparse
from . import total
def main():
parser = argparse.ArgumentParser()
parser.add_argument("amounts", type=int, nargs="+")
args = parser.parse_args()
print(total(args.amounts))
if __name__ == "__main__":
main()
在 project 根目录创建 pyproject.toml,与 src 并列。完整内容如下;它是 TOML 配置,按普通文本保存,不当作 Python 代码运行:
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "expensekit-demo"
version = "0.1.0"
description = "Local expense sum example"
requires-python = ">=3.12"
[project.scripts]
expense-total = "expensekit.cli:main"
[tool.setuptools.packages.find]
where = ["src"]
build-system 指定 setuptools 构建后端及其要求,project 声明本地项目名、版本与 Python 范围,project.scripts 把 expense-total 命令关联到 expensekit.cli:main。包发现从 src 开始,详见setuptools 的 pyproject 配置。
构建并安装到干净验证环境
进入包含 pyproject.toml 的 project 目录,在项目的构建环境执行:
python -m pip install build
python -m build
构建工具可能为隔离构建下载后端依赖,不能把网络安装失败当作源码一定有错。成功后 dist 应有 wheel 和源分发文件。build 的工作是调用后端构建分发,不会替你完成所有运行环境管理,见build 官方文档。
再创建单独的验证环境。以下命令在 project 目录执行:
python -m venv .venv-check
Windows PowerShell 使用新环境的解释器安装:
.\.venv-check\Scripts\python.exe -m pip install dist/expensekit_demo-0.1.0-py3-none-any.whl
macOS 或 Ubuntu 使用:
.venv-check/bin/python -m pip install dist/expensekit_demo-0.1.0-py3-none-any.whl
然后创建位于 project 之外的新目录并切换过去。执行下列检查前,应激活 .venv-check,或把其中的 python 替换为验证环境解释器的真实绝对路径。从其他目录不能继续照抄相对于 project 的旧路径。
python -c "from expensekit import total; print(total([3500,8000,2500]))"
python -m expensekit.cli 3500 8000 2500
两个命令都应输出 14000。激活验证环境后,expense-total 3500 8000 2500 也应调用同一 main 入口;也可使用验证环境中的完整 launcher 路径,Windows 为 Scripts/expense-total.exe,macOS 或 Linux 为 bin/expense-total。
检查 expensekit.__file__ 应指向新验证环境中安装的包,而不是 project/src。不要切换目录后无意使用已有开发环境的 Python,那可能让旧安装掩盖新 wheel 的遗漏。导入 CLI 不应自动解析参数,相关基础见包结构与运行入口。
核对分发内容、错误和本地验证范围
构建后的主要结构为:
project/
pyproject.toml
src/
expensekit/
__init__.py
cli.py
dist/
expensekit_demo-0.1.0-py3-none-any.whl
expensekit_demo-0.1.0.tar.gz
确认 wheel 包含 __init__.py 与 cli.py,元信息声明 Python >=3.12,入口对应 expensekit.cli:main。源分发也应包含 pyproject.toml 和两个源码文件,不应混入虚拟环境、缓存或秘密文件。只看到 dist 目录存在还不足以证明内容完整。
若导入仅在源码目录成功,检查实际解释器、已安装分发、包发现设置和 wheel 文件内容。外部运行依赖应声明在 project.dependencies,并验证支持的 Python 范围;开发工具不应不加区分地成为运行依赖。
再试零、负数、非数字和缺少参数。零合法;非数字与缺参由 argparse 返回状态 2,负数虽然被 CLI 转为 int,却由 total 抛 ValueError,当前程序以普通错误结束。这个简短界面尚未把所有业务错误统一成 argparse 消息,应如实理解它的契约。
本地验证完成意味着两种分发文件真实存在、包含预期模块,且新环境中的导入、模块 CLI 与命令别名在源码外可用。它不证明所有操作系统或未来版本都兼容,应另外测试准备声明支持的环境。
公共发行还需要检查名称、许可证、作者、README、包含文件和秘密信息、仓库认证与发布政策。这里的最小元信息适合本地学习;安装验证成功不会自动把包发布到 PyPI。




