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 包！