Python 打包与发布:setuptools 和 wheel 的全攻略
Python 项目打包与发布：setuptools 和 wheel
Python 提供了强大的工具链，用于将项目打包并分发到包管理器（如 PyPI）。setuptools 和 wheel 是其中的核心工具。
1. 什么是 setuptools 和 wheel？
- setuptools：用于构建和打包 Python 项目，支持依赖管理和复杂的配置。
- wheel：一种打包格式（.whl），是 Python 包的标准分发形式，安装速度快、效率高。
2. 项目打包的基础结构
以下是一个典型的项目结构：
arduino
Copy code
my_project/
├── my_package/
│ ├── __init__.py
│ ├── module1.py
│ └── module2.py
├── tests/
│ ├── test_module1.py
│ └── test_module2.py
├── setup.py
├── README.md
├── LICENSE
└── requirements.txt
- my_package/：核心代码。
- tests/：测试代码。
- setup.py：配置打包信息。
- requirements.txt：列出依赖项。
3. 创建 setup.py
setup.py 是项目打包的配置文件。以下是一个基本示例：
python
Copy code
from setuptools import setup, find_packages
setup(
name="my_project", # 项目名称
version="0.1.0", # 版本号
description="A sample Python project", # 简短描述
long_description=open("README.md").read(), # 详细描述
long_description_content_type="text/markdown", # 描述文件格式
author="Your Name", # 作者
author_email="your_email@example.com", # 作者邮箱
url="
https://github.com/your_username/my_project", # 项目主页
license="MIT", # 开源协议
packages=find_packages(), # 自动发现子包
install_requires=[ # 项目依赖
"numpy>=1.21.0",
"requests>=2.26.0"
],
classifiers=[ # 分类信息
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires=">=3.6", # 支持的 Python 版本
)
4. 构建项目
安装依赖
首先安装打包所需工具：
bash
Copy code
pip install setuptools wheel
构建分发包
在项目根目录运行以下命令：
bash
Copy code
python setup.py sdist bdist_wheel
- sdist：生成源代码分发包，通常是 .tar.gz 文件。
- bdist_wheel：生成 Wheel 分发包（.whl 文件）。
运行后，你将在项目的 dist/ 文件夹中看到生成的包文件。
5. 发布到 PyPI
安装发布工具
bash
Copy code
pip install twine
发布包
将生成的包上传到测试 PyPI（用于测试）：
bash
Copy code
twine upload --repository-url
https://test.pypi.org/legacy/ dist/*
验证测试包可用后，上传到正式 PyPI：
bash
Copy code
twine upload dist/*
验证发布
安装发布的包：
bash
Copy code
pip install my_project
6. 常见问题与解决方法
1. 没有生成 .whl文件
确保安装了 wheel 工具：
bash
Copy code
pip install wheel
2. 上传失败
检查 PyPI 的用户名和 API 密钥是否正确，或者检查网络连接。
3. 包含静态文件
如果项目中有非代码文件（如配置文件或图片），需要在 setup.py 中配置 include_package_data=True 并添加 MANIFEST.in 文件：
php
Copy code
include README.md
include LICENSE
recursive-include my_package/data *
7. 未来趋势
随着 Python 包管理的发展，以下工具也值得关注：
- poetry：更现代化的依赖管理和打包工具。
- flit：用于简单项目的轻量级打包工具。
通过本文的步骤，您可以快速上手 Python 项目的打包与发布，构建属于自己的 PyPI 包！