add pytest in makefile
This commit is contained in:
mm644706215
187
PACKAGING_GUIDE.md
Normal file
187
PACKAGING_GUIDE.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 🚀 Python 包发布到 PyPI 完整指南
|
||||
|
||||
## 📋 快速开始 (一键复现)
|
||||
|
||||
### 🚀 使用 Makefile (推荐)
|
||||
```bash
|
||||
make help # 查看所有命令
|
||||
make install # 安装开发环境
|
||||
make clean # 清理构建文件
|
||||
make build # 构建包
|
||||
make check # 检查包格式
|
||||
make publish # 发布到 PyPI
|
||||
make all # 运行所有检查和构建
|
||||
```
|
||||
|
||||
### 🔧 使用脚本
|
||||
```bash
|
||||
# 交互式发布 (推荐)
|
||||
python publish.py
|
||||
|
||||
# 自动发布到 PyPI (无交互)
|
||||
python publish.py --auto
|
||||
|
||||
# 发布到 TestPyPI
|
||||
python publish.py --test
|
||||
|
||||
# 仅构建和检查，不发布
|
||||
python publish.py --check-only
|
||||
```
|
||||
|
||||
### ⚡ 手动命令
|
||||
```bash
|
||||
# 环境准备
|
||||
UV_PYTHON=python3.12 uv venv .venv
|
||||
source .venv/bin/activate
|
||||
uv pip install -e ".[dev]"
|
||||
|
||||
# 构建发布
|
||||
rm -rf dist/ build/ *.egg-info/ src/*.egg-info/
|
||||
python -m build
|
||||
python -m twine check dist/*
|
||||
python -m twine upload dist/*
|
||||
```
|
||||
|
||||
## 📁 项目结构
|
||||
```
|
||||
project-name/
|
||||
├── pyproject.toml # ⭐ 核心配置文件
|
||||
├── README.md # 📖 项目文档
|
||||
├── LICENSE # 📄 许可证文件
|
||||
├── Makefile # 🔧 开发工具
|
||||
├── publish.py # 🚀 发布脚本
|
||||
├── src/
|
||||
│ └── package_name/
|
||||
│ ├── __init__.py # 包初始化
|
||||
│ └── module.py # 核心模块
|
||||
├── tests/
|
||||
│ └── test_module.py # 测试文件
|
||||
└── examples/
|
||||
└── basic_usage.py # 使用示例
|
||||
```
|
||||
|
||||
### ✅ 2. pyproject.toml 配置模板
|
||||
|
||||
```toml
|
||||
[project]
|
||||
name = "your-package-name"
|
||||
version = "0.1.0"
|
||||
description = "Your package description"
|
||||
readme = "README.md"
|
||||
authors = [
|
||||
{ name = "Your Name", email = "your.email@example.com" }
|
||||
]
|
||||
requires-python = ">=3.9"
|
||||
dependencies = [
|
||||
"dependency>=1.0.0",
|
||||
]
|
||||
keywords = ["keyword1", "keyword2"]
|
||||
classifiers = [
|
||||
"Development Status :: 4 - Beta",
|
||||
"Intended Audience :: Developers",
|
||||
"Programming Language :: Python :: 3",
|
||||
"Programming Language :: Python :: 3.9",
|
||||
"Programming Language :: Python :: 3.10",
|
||||
"Programming Language :: Python :: 3.11",
|
||||
"Programming Language :: Python :: 3.12",
|
||||
"Programming Language :: Python :: 3.13",
|
||||
"Topic :: Software Development :: Libraries :: Python Modules",
|
||||
]
|
||||
|
||||
[project.urls]
|
||||
Homepage = "https://github.com/username/repo"
|
||||
Repository = "https://github.com/username/repo"
|
||||
Documentation = "https://github.com/username/repo#readme"
|
||||
Issues = "https://github.com/username/repo/issues"
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = [
|
||||
# 测试工具
|
||||
"pytest>=7.0.0",
|
||||
"pytest-cov>=4.0.0",
|
||||
|
||||
# 代码格式化
|
||||
"black>=23.0.0",
|
||||
"isort>=5.12.0",
|
||||
|
||||
# 代码检查
|
||||
"flake8>=6.0.0",
|
||||
"mypy>=1.0.0",
|
||||
|
||||
# 打包工具 (仅开发环境需要)
|
||||
"build>=1.0.0",
|
||||
"twine>=4.0.0",
|
||||
"setuptools>=68.0.0",
|
||||
"wheel>=0.40.0",
|
||||
]
|
||||
|
||||
[build-system]
|
||||
requires = ["setuptools>=68.0.0", "wheel>=0.40.0"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
```
|
||||
|
||||
## 🔧 PyPI 认证配置
|
||||
|
||||
创建 `~/.pypirc` 文件：
|
||||
```ini
|
||||
[distutils]
|
||||
index-servers = pypi
|
||||
|
||||
[pypi]
|
||||
username = __token__
|
||||
password = pypi-your-api-token-here
|
||||
```
|
||||
|
||||
## ⚠️ 避免常见陷阱
|
||||
|
||||
1. **❌ 不要创建 build.py 文件** - 会与 `python -m build` 冲突
|
||||
2. **❌ 不要手动编辑许可证字段** - 使用 classifiers
|
||||
3. **❌ 不要混合开发和运行时依赖** - 打包工具放在 dev 依赖中
|
||||
4. **✅ 使用现代构建系统** - PEP 517/518 标准
|
||||
|
||||
## 🚨 故障排除
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
|------|----------|
|
||||
| build.py 冲突 | 重命名或删除项目中的 build.py |
|
||||
| 许可证元数据错误 | 移除 pyproject.toml 中的 license 字段 |
|
||||
| 包名冲突 | 在 PyPI 搜索确认包名可用性 |
|
||||
| 依赖解析失败 | 检查版本约束和兼容性 |
|
||||
|
||||
## ✅ 发布检查清单
|
||||
|
||||
- [ ] pyproject.toml 配置完整
|
||||
- [ ] README.md 文档详细
|
||||
- [ ] LICENSE 文件存在
|
||||
- [ ] 测试通过
|
||||
- [ ] `twine check` 通过
|
||||
- [ ] 版本号正确
|
||||
- [ ] PyPI 认证配置
|
||||
|
||||
## 🎯 版本兼容性
|
||||
|
||||
- **Python 版本**: 3.9-3.13
|
||||
- **Wheel 标签**: `py3-none-any` (通用兼容)
|
||||
- **构建系统**: setuptools (稳定可靠)
|
||||
|
||||
## 📝 最佳实践
|
||||
|
||||
1. **版本管理**: 使用语义化版本 (SemVer)
|
||||
2. **文档**: 提供完整的 README.md 和使用示例
|
||||
3. **测试**: 包含完整的测试套件
|
||||
4. **CI/CD**: 设置自动化测试和发布流程
|
||||
5. **安全**: 使用 API token 而不是用户名密码
|
||||
|
||||
## <20> 发布后验证
|
||||
|
||||
```bash
|
||||
# 安装验证
|
||||
pip install your-package-name
|
||||
|
||||
# 功能验证
|
||||
python -c "import your_package; print('✅ 安装成功')"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**这个指南确保每次都能成功发布到 PyPI！** 🚀
|
||||
Reference in New Issue
Block a user