# PyHiVision 发布指南

本文档详细说明如何将 PyHiVision 发布到 PyPI（Python Package Index）。

---

## 📋 发布前检查清单

在发布之前，请确保完成以下检查：

- [ ] 所有代码已提交到 Git
- [ ] 所有测试通过（`pytest tests/`）
- [ ] 代码格式检查通过（`ruff check .`）
- [ ] 更新了 `pyproject.toml` 中的版本号
- [ ] 更新了 `CHANGELOG.md`（如果有）
- [ ] 更新了 `README.md`（如果有新功能）
- [ ] 确认许可证信息正确
- [ ] 确认所有依赖版本正确

---

## 🛠️ 第一步：安装构建工具

首先安装发布所需的工具：

```bash
# 安装构建工具
pip install --upgrade build twine

# 或者使用 uv（更快）
uv pip install build twine
```

**工具说明：**
- `build`: 用于构建 Python 包（wheel 和 sdist）
- `twine`: 用于安全上传包到 PyPI

---

## 📦 第二步：构建包

### 清理旧的构建文件

```bash
# 删除旧的构建产物
rm -rf dist/ build/ *.egg-info
# Windows PowerShell
Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue
```

### 构建包

```bash
# 构建源码包（sdist）和二进制包（wheel）
python -m build

# 或者使用 uv（推荐，更快）
uv build
```

执行成功后，会在 `dist/` 目录下生成两个文件：
- `pyhivision-1.0.0.tar.gz` - 源码分发包
- `pyhivision-1.0.0-py3-none-any.whl` - wheel 二进制包

---

## 🔍 第三步：本地测试包

### 检查包的完整性

```bash
# 检查生成的包是否符合规范
twine check dist/*
```

如果没有错误或警告，会显示：
```
Checking dist/pyhivision-1.0.0-py3-none-any.whl: PASSED
Checking dist/pyhivision-1.0.0.tar.gz: PASSED
```

### 本地安装测试

```bash
# 创建测试虚拟环境
python -m venv test_env
source test_env/bin/activate  # Linux/Mac
# 或
test_env\Scripts\activate  # Windows

# 从构建的包安装
pip install dist/pyhivision-1.0.0-py3-none-any.whl

# 测试导入
python -c "from pyhivision import IDPhotoSDK; print('Import successful!')"

# 退出测试环境
deactivate
```

---

## 🚀 第四步：发布到 PyPI

### 4.1 注册 PyPI 账号

1. 访问 [PyPI](https://pypi.org/) 注册账号
2. 访问 [TestPyPI](https://test.pypi.org/) 注册测试账号（推荐先在这里测试）
3. 在账号设置中生成 API Token

### 4.2 配置 PyPI 凭证

**方式一：使用 `.pypirc` 配置文件（推荐）**

在用户目录创建 `~/.pypirc` 文件（Windows: `C:\Users\你的用户名\.pypirc`）：

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-AgENd... # 你的 PyPI API Token

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-AgENd... # 你的 TestPyPI API Token
```

**方式二：使用环境变量**

```bash
# Linux/Mac
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-AgENd...

# Windows PowerShell
$env:TWINE_USERNAME="__token__"
$env:TWINE_PASSWORD="pypi-AgENd..."
```

### 4.3 发布到 TestPyPI（测试）

**强烈建议先在 TestPyPI 测试！**

```bash
# 上传到 TestPyPI
twine upload --repository testpypi dist/*
```

成功后，访问 https://test.pypi.org/project/pyhivision/ 查看包。

#### 从 TestPyPI 安装测试

```bash
# 从 TestPyPI 安装（注意依赖可能需要从正式 PyPI 获取）
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    pyhivision
```

### 4.4 发布到正式 PyPI

确认 TestPyPI 测试无误后，发布到正式 PyPI：

```bash
# 上传到 PyPI
twine upload dist/*
```

成功后，访问 https://pypi.org/project/pyhivision/ 查看包。

#### 安装验证

```bash
# 从 PyPI 安装
pip install pyhivision

# 验证安装
python -c "from pyhivision import __version__; print(f'PyHiVision {__version__} installed successfully!')"
```

---

## 🔄 版本管理

### 语义化版本控制（SemVer）

版本号格式：`主版本号.次版本号.修订号`（例如：`1.0.0`）

- **主版本号（MAJOR）**：不兼容的 API 修改
- **次版本号（MINOR）**：向下兼容的功能新增
- **修订号（PATCH）**：向下兼容的 bug 修复

**示例：**
- `1.0.0` → `1.0.1` - 修复 bug
- `1.0.1` → `1.1.0` - 新增功能
- `1.1.0` → `2.0.0` - 破坏性变更

### 更新版本号

编辑 `pyproject.toml`：

```toml
[project]
name = "pyhivision"
version = "1.0.1"  # 更新这里
```

或使用 `bump2version` 自动管理：

```bash
# 安装
pip install bump2version

# 使用
bump2version patch  # 1.0.0 -> 1.0.1
bump2version minor  # 1.0.0 -> 1.1.0
bump2version major  # 1.0.0 -> 2.0.0
```

---

## 🤖 自动化发布（GitHub Actions）

### 创建发布工作流

创建 `.github/workflows/publish.yml`：

```yaml
name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # 用于 Trusted Publishers

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install build tools
        run: pip install build twine

      - name: Build package
        run: python -m build

      - name: Check package
        run: twine check dist/*

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}
```

### 配置 GitHub Secrets

在 GitHub 仓库设置中添加 Secret：
- **Settings** → **Secrets and variables** → **Actions**
- 添加 `PYPI_API_TOKEN`，值为你的 PyPI API Token

### 发布新版本

```bash
# 1. 更新版本号
# 编辑 pyproject.toml: version = "1.0.1"

# 2. 提交更改
git add .
git commit -m "Bump version to 1.0.1"
git push

# 3. 创建 Git 标签
git tag v1.0.1
git push origin v1.0.1

# 4. 在 GitHub 上创建 Release
# 访问 https://github.com/ZyphrZero/pyhivision/releases/new
# 选择 v1.0.1 标签，填写 Release 说明，点击 Publish
```

GitHub Actions 会自动构建并发布到 PyPI。

---

## 📝 发布后检查

发布成功后，验证以下内容：

1. **PyPI 页面**：访问 https://pypi.org/project/pyhivision/
   - 检查版本号是否正确
   - 检查描述（README.md）显示是否正常
   - 检查分类器和关键词

2. **安装测试**：
   ```bash
   # 在干净的环境中安装
   pip install pyhivision==1.0.0

   # 测试导入
   python -c "from pyhivision import IDPhotoSDK"
   ```

3. **文档检查**：
   - 检查 GitHub README 徽章是否更新
   - 检查版本号是否一致

---

## 🚨 常见问题

### 1. `twine upload` 失败：403 Forbidden

**原因**：包名已被占用或没有权限

**解决**：
- 确认包名在 PyPI 上未被占用
- 检查 API Token 是否正确
- 确认你是包的维护者（重新上传时）

### 2. 构建失败：找不到模块

**原因**：`MANIFEST.in` 配置不正确

**解决**：
- 确保所有必要的文件都包含在 MANIFEST.in 中
- 检查 `pyproject.toml` 的 `packages` 配置

### 3. 依赖安装失败

**原因**：依赖版本冲突

**解决**：
- 检查 `pyproject.toml` 中的依赖版本范围
- 使用 `pip install --dry-run` 测试依赖

### 4. 版本号已存在

**原因**：PyPI 不允许重新上传相同版本号

**解决**：
- 删除 `dist/` 目录
- 更新 `pyproject.toml` 中的版本号
- 重新构建和上传

---

## 📚 参考资源

- [Python 打包用户指南](https://packaging.python.org/)
- [PyPI 官方文档](https://pypi.org/help/)
- [Twine 文档](https://twine.readthedocs.io/)
- [语义化版本控制](https://semver.org/lang/zh-CN/)
- [PEP 517 - 构建系统接口](https://www.python.org/dev/peps/pep-0517/)
- [PEP 621 - 项目元数据](https://www.python.org/dev/peps/pep-0621/)

---

## 🎯 快速发布命令总结

```bash
# 1. 更新版本号（编辑 pyproject.toml）

# 2. 清理旧构建
rm -rf dist/ build/ *.egg-info

# 3. 构建包
python -m build

# 4. 检查包
twine check dist/*

# 5. 测试发布（可选但推荐）
twine upload --repository testpypi dist/*

# 6. 正式发布
twine upload dist/*

# 7. 创建 Git 标签
git tag v1.0.0
git push origin v1.0.0
```

---

**祝发布顺利！** 🎉

如有问题，请访问 [GitHub Issues](https://github.com/ZyphrZero/pyhivision/issues)。
