# 🚀 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 而不是用户名密码

## � 发布后验证

```bash
# 安装验证
pip install your-package-name

# 功能验证
python -c "import your_package; print('✅ 安装成功')"
```

---

**这个指南确保每次都能成功发布到 PyPI！** 🚀