打包与发布Python包

发布时间: 2025-04-02 10:37

↑

# 打包与发布Python包

本文将介绍如何将Python项目打包并发布到PyPI（Python Package Index）。我们将学习使用setuptools和wheel等工具进行打包，以及如何将包发布到PyPI。

## 项目结构

一个标准的Python包项目结构如下：

```
my_package/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── core.py
├── tests/
│   └── test_core.py
├── README.md
├── LICENSE
├── pyproject.toml
├── setup.cfg
└── setup.py
```

## 配置文件

### 1. pyproject.toml

```toml
[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

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

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

### 2. setup.cfg

```ini
[metadata]
name = my-package
version = 0.1.0
author = Your Name
author_email = your.email@example.com
description = A sample Python package
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/username/my-package
classifiers =
    Programming Language :: Python :: 3
    License :: OSI Approved :: MIT License
    Operating System :: OS Independent

[options]
package_dir =
    = src
packages = find:
python_requires = >=3.7

[options.packages.find]
where = src
```

### 3. setup.py（可选）

```python
from setuptools import setup

setup()
```

## 打包工具

### 1. setuptools

setuptools是Python包的标准构建工具：

```bash
# 安装setuptools
pip install --upgrade setuptools wheel

# 构建包
python setup.py sdist bdist_wheel
```

### 2. build

build是一个更现代的打包工具：

```bash
# 安装build
pip install build

# 构建包
python -m build
```

## 发布到PyPI

### 1. 注册PyPI账号

1. 访问 https://pypi.org/account/register/ 注册账号
2. 创建API令牌：https://pypi.org/manage/account/token/

### 2. 配置发布工具

```bash
# 安装twine
pip install twine

# 创建.pypirc配置文件
cat > ~/.pypirc << EOF
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = your-api-token

[testpypi]
username = __token__
password = your-test-api-token
repository = https://test.pypi.org/legacy/
EOF

# 设置文件权限
chmod 600 ~/.pypirc
```

### 3. 发布包

```bash
# 检查分发包
twine check dist/*

# 发布到TestPyPI（推荐先测试）
twine upload --repository testpypi dist/*

# 发布到PyPI
twine upload dist/*
```

## 版本管理

### 1. 版本号规范

遵循语义化版本（Semantic Versioning）：
- 主版本号：不兼容的API修改
- 次版本号：向下兼容的功能性新增
- 修订号：向下兼容的问题修正

### 2. 版本更新

```bash
# 更新版本号
sed -i 's/version = "0.1.0"/version = "0.1.1"/' pyproject.toml

# 创建Git标签
git tag v0.1.1
git push origin v0.1.1
```

## 最佳实践

1. **使用src布局**：将包源码放在src目录下
2. **完善文档**：编写详细的README和文档
3. **添加测试**：包含单元测试和集成测试
4. **版本控制**：使用Git管理代码和版本
5. **CI/CD**：配置自动化测试和发布

## 常见问题

### 1. 包名冲突

- 在PyPI上搜索包名是否已存在
- 使用具有描述性的唯一包名
- 考虑使用命名空间包

### 2. 依赖问题

- 明确指定依赖版本范围
- 使用`install_requires`声明运行时依赖
- 使用`extras_require`声明可选依赖

### 3. 文件包含

- 使用MANIFEST.in包含额外文件
- 在setup.cfg中配置package_data
- 检查wheel包内容是否完整

## 总结

打包和发布是Python项目的重要环节。通过合理的项目结构、配置文件和工具使用，我们可以将Python包规范地发布到PyPI，供其他开发者使用。记住要遵循最佳实践，确保包的质量和可维护性。

元素码农