第197集：Python项目打包与发布

课程目标

  • 了解Python项目打包的基本概念
  • 掌握使用setuptools和pyproject.toml配置项目
  • 学会构建和安装Python包
  • 掌握使用PyInstaller创建可执行文件
  • 了解发布包到PyPI的流程

一、Python打包基础

1.1 什么是打包？

Python打包是将Python代码、依赖和资源组织成一个可分发的格式，方便其他开发者安装和使用。

1.2 打包的优势

  • 便于代码分发和共享
  • 自动处理依赖关系
  • 提供标准化的安装方式
  • 支持版本管理
  • 便于项目维护和升级

二、项目结构

2.1 标准项目结构

my_project/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   └── test_module1.py
├── pyproject.toml
├── setup.cfg
├── README.md
└── LICENSE

2.2 各文件的作用

  • my_package/: 主包目录
  • tests/: 测试代码目录
  • pyproject.toml: 项目配置文件（现代方式）
  • setup.cfg: 构建配置文件
  • README.md: 项目说明文档
  • LICENSE: 许可证文件

三、使用pyproject.toml配置项目

3.1 基本配置

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "0.1.0"
authors = [
  { name = "Your Name", email = "your.email@example.com" },
]
description = "A simple Python package"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
"Homepage" = "https://github.com/yourusername/my-package"
"Bug Tracker" = "https://github.com/yourusername/my-package/issues"

3.2 添加依赖

[project.dependencies]
requests = ">=2.0.0"
pandas = ">=1.5.0"

3.3 添加开发依赖

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=22.0",
    "flake8>=5.0",
]

四、构建和安装包

4.1 构建包

# 安装构建工具
pip install build

# 构建包
python -m build

构建完成后，会在dist/目录下生成两种格式的包：

  • .tar.gz: 源代码包
  • .whl: 轮子包（二进制格式，安装更快）

4.2 安装包

# 安装本地包
pip install dist/my_package-0.1.0-py3-none-any.whl

# 开发模式安装（便于调试）
pip install -e .

五、使用PyInstaller创建可执行文件

5.1 安装PyInstaller

pip install pyinstaller

5.2 创建单个文件可执行文件

pyinstaller --onefile my_script.py

5.3 创建带窗口的可执行文件（Windows）

pyinstaller --onefile --windowed my_script.py

5.4 包含数据文件

pyinstaller --onefile --add-data "data.txt;." my_script.py

5.5 使用.spec文件自定义构建

# 生成spec文件
pyinstaller --name=my_app my_script.py

# 编辑spec文件后构建
pyinstaller my_app.spec

六、发布到PyPI

6.1 注册PyPI账号

访问 PyPI官网 注册账号。

6.2 安装twine

pip install twine

6.3 上传包到PyPI

# 上传到PyPI
twine upload dist/*

# 上传到TestPyPI（测试环境）
twine upload --repository testpypi dist/*

6.4 安装来自PyPI的包

pip install my-package

七、最佳实践

7.1 版本管理

  • 使用语义化版本（Major.Minor.Patch）
  • 记录版本变更日志（CHANGELOG.md）

7.2 文档

  • 编写清晰的README.md
  • 使用Sphinx生成API文档
  • 提供示例代码

7.3 测试

  • 编写单元测试
  • 使用CI/CD自动运行测试
  • 确保测试覆盖率

7.4 安全

  • 定期更新依赖
  • 扫描安全漏洞
  • 避免包含敏感信息

八、常见问题

8.1 包安装后无法导入

  • 检查包名是否正确
  • 确认包已正确安装
  • 检查PYTHONPATH环境变量

8.2 PyInstaller构建失败

  • 检查依赖是否完整
  • 使用--debug参数查看详细错误
  • 确保所有资源文件都已正确包含

8.3 上传到PyPI失败

  • 检查版本号是否已存在
  • 确认包名是否可用
  • 检查网络连接

九、总结

Python打包与发布是项目开发的重要环节，通过本节课的学习，您应该掌握了：

  • 如何组织项目结构
  • 使用pyproject.toml配置项目
  • 构建和安装Python包
  • 使用PyInstaller创建可执行文件
  • 发布包到PyPI的流程

下一节课，我们将学习Python项目的服务器部署。

« 上一篇 文档编写 下一篇 » 服务器部署
↑