rustfs-s3-toolkit/PACKAGING_GUIDE.md

🚀 Python 包发布到 PyPI 完整指南

📋 快速开始 (一键复现)

🚀 使用 Makefile (推荐)

make help          # 查看所有命令
make install       # 安装开发环境
make clean         # 清理构建文件
make build         # 构建包
make check         # 检查包格式
make publish       # 发布到 PyPI
make all           # 运行所有检查和构建

🔧 使用脚本

# 交互式发布 (推荐)
python publish.py

# 自动发布到 PyPI (无交互)
python publish.py --auto

# 发布到 TestPyPI
python publish.py --test

# 仅构建和检查，不发布
python publish.py --check-only

⚡ 手动命令

# 环境准备
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 配置模板

[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 文件：

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

<EFBFBD> 发布后验证

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

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

---

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