如何将 Python 项目打包成 Wheel 格式

随着 Python 生态系统的不断发展打包和分发 Python 项目已成为开发者日常工作的重要组成部分。Wheel 格式作为 Python 的二进制分发格式相比传统的源码分发具有安装速度快、依赖关系明确、跨平台兼容等优势。本文将按照实际开发流程从项目结构到测试再到打包配置系统性地介绍如何将 Python 项目打包成 wheel 格式。项目结构设计良好的项目结构是成功打包的基础。推荐使用以下结构my_project/ ├── src/ │ └── my_package/ │ ├── __init__.py │ └── main.py ├── tests/ │ └── test_main.py ├── Makefile ├── pyproject.toml ├── README.md ├── LICENSE └── .gitignore这种结构采用src布局有助于避免导入问题并保持项目的整洁。源代码实现包初始化文件src/my_package/init.py:My sample package.__version__0.1.0from.mainimporthello_world __all__[hello_world]核心功能模块src/my_package/main.py:defhello_world():Simple function that returns a greeting.returnHello, World!defadd_numbers(a,b):Add two numbers together.returnab测试实现编写适当的测试文件确保代码质量tests/test_main.py:测试 my_package 模块deftest_hello_world():frommy_packageimporthello_worldasserthello_world()Hello, World!deftest_add_numbers():frommy_package.mainimportadd_numbersassertadd_numbers(2,3)5assertadd_numbers(-1,1)0打包配置pyproject.toml 文件现代 Python 打包推荐使用pyproject.toml文件它包含了项目的全部配置信息[build-system] requires [setuptools45, wheel] build-backend setuptools.build_meta [project] name my-package version 0.1.0 description A sample Python package readme README.md authors [ {name Your Name, email your.emailexample.com} ] license {text MIT} classifiers [ Development Status :: 3 - Alpha, Intended Audience :: Developers, License :: OSI Approved :: MIT License, Programming Language :: Python :: 3, Programming Language :: Python :: 3.8, Programming Language :: Python :: 3.9, Programming Language :: Python :: 3.10, Programming Language :: Python :: 3.11, ] dependencies [ # 项目依赖项 ] [project.optional-dependencies] dev [ pytest6.0, black, flake8, ] [project.urls] Homepage https://github.com/yourusername/my-package Repository https://github.com/yourusername/my-package [tool.setuptools.packages.find] where [src] [tool.setuptools.package-dir] src环境准备在开始打包之前需要安装必要的工具pipinstall--upgradepip setuptools wheel build twine这些工具分别是setuptoolsPython 打包的核心工具wheel支持 wheel 格式的构建build现代化的构建工具twine用于上传包到 PyPI构建与验证流程使用 Makefile 管理流程为了更好地管理打包流程我们可以创建一个功能完整的 Makefile.PHONY: help build clean test install upload verify dev-install local-test # 默认目标显示帮助信息 help: echo 可用的 make 命令: echo build - 构建 wheel 包 echo clean - 清理构建文件 echo test - 运行测试 echo dev-install - 开发模式安装 echo verify - 验证 wheel 文件 echo local-test - 本地测试安装 echo upload - 上传到 PyPI # 安装构建工具 setup-tools: pip install --upgrade pip setuptools wheel build twine # 构建 wheel 包 build: setup-tools echo 正在构建 wheel 包... rm -rf dist/ build/ *.egg-info/ python -m build --wheel echo 构建完成 ls -la dist/ # 清理构建文件 clean: echo 清理构建文件... rm -rf dist/ build/ *.egg-info/ .pytest_cache/ __pycache__/ # 开发模式安装 dev-install: setup-tools echo 以开发模式安装... pip install -e . # 运行测试 test: echo 运行测试... python -m pytest tests/ -v # 验证 wheel 文件 verify: build echo 验证 wheel 文件... for wheel in dist/*.whl; do \ echo 检查 $$wheel; \ pip install $$wheel; \ python -c import my_package; print(Import successful:, my_package.hello_world()); \ done # 本地测试安装使用临时虚拟环境 local-test: build echo 在临时环境中测试安装... python -c import tempfile, subprocess, os, sys; \ temp_dir tempfile.mkdtemp(); \ print(f创建临时目录: {temp_dir}); \ subprocess.check_call([python, -m, venv, os.path.join(temp_dir, test_env)]); \ pip_path os.path.join(temp_dir, test_env, Scripts, pip) if sys.platform.startswith(win) else os.path.join(temp_dir, test_env, bin, pip); \ wheel_file [f for f in os.listdir(dist) if f.endswith(.whl)][0]; \ subprocess.check_call([pip_path, install, os.path.join(dist, wheel_file)]); \ python_path os.path.join(temp_dir, test_env, Scripts, python) if sys.platform.startswith(win) else os.path.join(temp_dir, test_env, bin, python); \ subprocess.check_call([python_path, -c, import my_package; print(my_package.hello_world())]); \ print(本地测试通过); \ import shutil; \ shutil.rmtree(temp_dir) # 上传到 PyPI upload: build echo 上传到 PyPI... twine check dist/* twine upload dist/* # 检查依赖 check-deps: echo 检查项目依赖... pip check构建与验证步骤构建 wheel 包makebuild运行测试maketest验证 wheel 包makeverify本地测试安装makelocal-test安装示例构建完成后wheel 文件位于dist/目录中。最简单的安装方式如下pipinstalldist/my_package-0.1.0-py3-none-any.whl上传到 PyPI当一切准备就绪后可以将包上传到 PyPI首先注册 PyPI 账户安装 twinepip install twine上传包make upload最佳实践建议使用 pyproject.toml现代 Python 打包的标准配置文件版本管理遵循语义化版本规范依赖管理明确指定依赖版本范围测试覆盖确保有充分的测试覆盖文档完善提供清晰的 README 和文档持续集成使用 CI 工具自动化测试和发布wheel 安装测试在发布前务必测试 wheel 文件的安装和使用常见问题及解决方案找不到包检查pyproject.toml中的包路径配置依赖冲突仔细管理依赖版本平台兼容性测试不同平台的兼容性权限问题确保 PyPI 上传权限正确安装失败检查 wheel 文件是否完整且未损坏总结本文按照实际开发流程从项目结构、源代码实现、测试编写到打包配置系统性地介绍了如何将 Python 项目打包成 wheel 格式。通过合理的项目组织和现代化的打包工具可以大大提高开发效率和包的质量。Wheel 格式作为 Python 包分发的未来趋势掌握其打包方法对于 Python 开发者来说非常重要。希望本文能帮助您更好地理解和应用 Python 包打包技术提升您的开发效率和项目质量。