# 发布指南

本指南说明如何使用 `uv` 将 SerpShot Python SDK 发布到 PyPI。

## 快速开始

最简单的发布方式（3 步）：

```bash
# 1. 更新版本号（如果需要）
# 编辑 pyproject.toml 和 serpshot/__init__.py 中的版本号

# 2. 构建包
uv build --no-sources

# 3. 发布到 PyPI
uv publish --token pypi-your-token-here
```

或者使用提供的脚本（Windows PowerShell）：
```powershell
.\publish.ps1
```

或（Linux/Mac）：
```bash
chmod +x publish.sh
./publish.sh
```

## 前置准备

1. **确保已安装 uv**：
   ```bash
   # 如果还没有安装，可以通过以下方式安装
   curl -LsSf https://astral.sh/uv/install.sh | sh
   # 或使用 pip
   pip install uv
   ```

2. **准备 PyPI 凭证**：
   - 在 [PyPI](https://pypi.org) 注册账号
   - 生成 API Token：
     - 登录 PyPI → Account settings → API tokens → Add API token
     - 选择 "Entire account" 或特定项目范围
     - 复制生成的 token（格式：`pypi-...`）

3. **检查项目配置**：
   - 确认 `pyproject.toml` 中的版本号、描述等信息正确
   - 确认所有代码已提交到 git

## 发布步骤

### 1. 更新版本号（可选）

如果需要更新版本，需要手动更新两个文件中的版本号：

1. **更新 `pyproject.toml`**：
   ```toml
   [project]
   version = "0.1.1"  # 更新这里
   ```

2. **更新 `serpshot/__init__.py`**：
   ```python
   __version__ = "0.1.1"  # 更新这里
   ```

**注意**：确保两个文件中的版本号保持一致。

> 💡 **提示**：如果使用较新版本的 uv（支持 `uv version` 命令），可以使用：
> ```bash
> uv version 0.1.1  # 或 uv version --bump patch
> ```
> 这会自动同步两个文件中的版本号。

### 2. 构建包

```bash
# 构建包（推荐使用 --no-sources 确保构建正确）
uv build --no-sources
```

构建产物会生成在 `dist/` 目录：
- `serpshot-X.X.X.tar.gz` - 源码分发
- `serpshot-X.X.X-py3-none-any.whl` - wheel 分发

### 3. 测试安装（可选但推荐）

在发布前，可以测试安装构建的包：

```bash
# 测试安装 wheel
uv run --no-project --with dist/serpshot-*.whl -- python -c "import serpshot; print(serpshot.__version__)"
```

### 4. 发布到 PyPI

#### 方式一：使用环境变量（推荐）

```bash
# Windows PowerShell
$env:UV_PUBLISH_TOKEN="pypi-your-token-here"
uv publish

# Linux/Mac
export UV_PUBLISH_TOKEN="pypi-your-token-here"
uv publish
```

#### 方式二：使用命令行参数

```bash
uv publish --token pypi-your-token-here
```

#### 方式三：使用 Trusted Publisher（GitHub Actions）

如果使用 GitHub Actions 自动发布，可以配置 Trusted Publisher，无需设置 token。详见 [uv GitHub Actions 指南](https://docs.astral.sh/uv/guides/integrations/github-actions/)。

### 5. 发布到 TestPyPI（测试，可选）

首次发布前，建议先发布到 TestPyPI 进行测试：

```bash
# 在 pyproject.toml 中添加测试索引配置
# [[tool.uv.index]]
# name = "testpypi"
# url = "https://test.pypi.org/simple/"
# publish-url = "https://test.pypi.org/legacy/"
# explicit = true

# 发布到 TestPyPI
uv publish --index testpypi --token pypi-your-testpypi-token
```

然后测试安装：
```bash
uv add --index https://test.pypi.org/simple/ serpshot
```

## 发布后验证

发布成功后，验证包是否可用：

```bash
# 等待几分钟让 PyPI 索引更新，然后测试安装
uv run --no-project --with serpshot -- python -c "import serpshot; print(serpshot.__version__)"
```

## 常见问题

### 发布失败，部分文件已上传

如果发布过程中断，可以重新运行相同的 `uv publish` 命令。PyPI 会忽略已存在的相同文件。

### 版本已存在

如果 PyPI 上已存在相同版本，需要先更新版本号：
1. 手动更新 `pyproject.toml` 和 `serpshot/__init__.py` 中的版本号
2. 重新构建和发布：
```bash
uv build --no-sources
uv publish --token your-token
```

### 需要更新已发布的版本

PyPI 不允许删除或修改已发布的版本。如果发现问题，需要发布新的版本号。

## 自动化发布（GitHub Actions 示例）

可以在 `.github/workflows/publish.yml` 中配置自动发布：

```yaml
name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
      - name: Build and publish
        run: |
          uv build --no-sources
          uv publish --token ${{ secrets.PYPI_API_TOKEN }}
```

## 参考链接

- [uv 发布包指南](https://docs.astral.sh/uv/guides/package/)
- [PyPI 文档](https://packaging.python.org/)
- [Python 打包用户指南](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/)

