# PyPI 上传指南

本指南将帮助您将 AlayaFlow 项目上传到 PyPI。

## 📋 前置准备

### 1. 更新项目信息

在开始之前，请确保完成以下修改：

#### 1.1 更新 `pyproject.toml` 中的作者信息

编辑 `pyproject.toml` 文件，将以下内容替换为您的真实信息：

```toml
authors = [
  {name = "Your Name", email = "your.email@example.com"}
]
```

#### 1.2 添加项目元数据（可选但推荐）

在 `pyproject.toml` 的 `[project]` 部分添加：

```toml
keywords = ["langgraph", "workflow", "langchain", "ai", "automation"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Software Development :: Libraries :: Python Modules",
]
```

#### 1.3 添加项目 URL（可选）

如果有 GitHub 仓库或其他主页，可以添加：

```toml
urls = {
    Homepage = "https://github.com/yourusername/alayaflow",
    Documentation = "https://github.com/yourusername/alayaflow#readme",
    Repository = "https://github.com/yourusername/alayaflow"
}
```

### 2. 创建 PyPI 账户

1. **访问 [PyPI](https://pypi.org/account/register/)** 注册账户
2. **访问 [TestPyPI](https://test.pypi.org/account/register/)** 注册测试账户（强烈推荐先测试）

### 3. 安装构建工具

确保已安装最新版本的构建和上传工具：

```bash
pip install --upgrade build twine
```

## 🚀 构建和上传流程

### 步骤 1: 清理旧的构建文件

```bash
# 删除旧的构建文件
rm -rf dist/ build/ *.egg-info src/*.egg-info
```

### 步骤 2: 构建分发包

```bash
# 使用 pyproject.toml 构建
python -m build
```

这将创建 `dist/` 目录，包含：
- `alayaflow-0.1.0.tar.gz` (源码分发包)
- `alayaflow-0.1.0-py3-none-any.whl` (wheel 分发包)

### 步骤 3: 检查构建结果（推荐）

```bash
# 检查分发包
twine check dist/*
```

如果检查通过，您会看到类似输出：
```
Checking dist/alayaflow-0.1.0-py3-none-any.whl: PASSED
Checking dist/alayaflow-0.1.0.tar.gz: PASSED
```

### 步骤 4: 测试上传到 TestPyPI

**强烈建议先上传到 TestPyPI 进行测试！**

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

系统会提示您输入：
- **用户名**：您的 TestPyPI 用户名
- **密码**：您的 TestPyPI 密码（或 API token）

#### 使用 API Token（推荐，更安全）

1. 登录 [TestPyPI](https://test.pypi.org/manage/account/)
2. 滚动到 "API tokens" 部分
3. 点击 "Add API token"
4. 输入 token 名称（如 "alayaflow-upload"）
5. 选择作用域（建议选择 "Entire account"）
6. 点击 "Add token"
7. **复制生成的 token**（格式：`pypi-xxxxxxxxxxxxx`，只显示一次！）

上传时：
- 用户名输入：`__token__`
- 密码输入：完整的 token（包括 `pypi-` 前缀）

### 步骤 5: 从 TestPyPI 测试安装

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

# 从 TestPyPI 安装
pip install --index-url https://test.pypi.org/simple/ alayaflow

# 测试导入
python -c "import alayaflow; print(alayaflow.__version__)"
```

### 步骤 6: 上传到正式 PyPI

测试成功后，上传到正式 PyPI：

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

同样，您可以使用 API token 进行认证（在 [PyPI](https://pypi.org/manage/account/) 创建）。

## 🔧 使用 .pypirc 配置文件（可选）

为了简化上传过程，可以创建 `~/.pypirc` 文件（Linux/Mac）或 `%USERPROFILE%\.pypirc`（Windows）：

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

[pypi]
username = __token__
password = pypi-your-actual-pypi-token-here

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-your-testpypi-token-here
```

**⚠️ 安全提示：** 如果使用 `.pypirc`，请确保文件权限设置为仅所有者可读：

```bash
# Linux/Mac
chmod 600 ~/.pypirc

# Windows (在 PowerShell 中)
icacls $env:USERPROFILE\.pypirc /inheritance:r
icacls $env:USERPROFILE\.pypirc /grant:r "%USERNAME%:R"
```

使用配置文件后，上传命令简化为：

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

# 上传到正式 PyPI
twine upload dist/*
```

## 📦 更新版本

每次发布新版本时：

1. **更新 `pyproject.toml` 中的版本号**：
   ```toml
   version = "0.1.1"  # 例如从 0.1.0 升级到 0.1.1
   ```

2. **更新 `src/alayaflow/__init__.py` 中的版本号**：
   ```python
   __version__ = "0.1.1"
   ```

3. **重新构建和上传**：
   ```bash
   rm -rf dist/ build/ *.egg-info
   python -m build
   twine check dist/*
   twine upload dist/*
   ```

## 📝 版本号规范

遵循 [语义化版本](https://semver.org/)：
- **主版本号** (MAJOR): 不兼容的 API 修改
- **次版本号** (MINOR): 向后兼容的功能新增
- **修订号** (PATCH): 向后兼容的问题修复

示例：
- `1.2.3` → `1.2.4` (修复 bug)
- `1.2.3` → `1.3.0` (新功能)
- `1.2.3` → `2.0.0` (重大变更)

## ❓ 常见问题

### 1. 包名已被占用

如果 `alayaflow` 已被占用，需要：
- 在 PyPI 上搜索确认：https://pypi.org/project/alayaflow/
- 修改 `pyproject.toml` 中的 `name` 字段
- 确保包名符合 PyPI 命名规范（只能包含字母、数字、连字符和下划线）

### 2. 上传失败：文件已存在

如果版本号已存在，需要：
- 增加版本号
- 或者删除旧版本（需要 PyPI 管理员权限，且不推荐）

### 3. 依赖问题

确保所有依赖都在 `dependencies` 中正确列出，并且版本约束合理。检查：
- 所有必需的依赖都已列出
- 版本约束不会过于严格（如 `>=` 而不是 `==`）

### 4. 许可证问题

当前项目使用 MIT 许可证。确保：
- `LICENSE` 文件存在（如果使用文件）
- `pyproject.toml` 中的许可证信息正确：`license = {text = "MIT"}`

### 5. 构建失败

如果 `python -m build` 失败：
- 检查 `pyproject.toml` 语法是否正确
- 确保已安装 `build` 包：`pip install build`
- 检查 `src/alayaflow/__init__.py` 是否存在

## ✅ 上传前检查清单

- [ ] 作者信息已更新为真实信息
- [ ] 版本号已更新（如果是新版本）
- [ ] README.md 完整且准确
- [ ] 所有依赖已正确列出
- [ ] 许可证信息正确（MIT）
- [ ] 已通过 `twine check` 检查
- [ ] 已在 TestPyPI 上测试安装
- [ ] 没有包含敏感信息（API keys、密码等）
- [ ] `.gitignore` 已正确配置，不会上传不必要的文件
- [ ] 包名在 PyPI 上可用

## 📚 参考资源

- [PyPI 官方文档](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/)
- [Twine 文档](https://twine.readthedocs.io/)
- [Python 打包用户指南](https://packaging.python.org/)
- [PyPI 账户管理](https://pypi.org/manage/account/)
- [TestPyPI 账户管理](https://test.pypi.org/manage/account/)

## 🎯 快速命令参考

```bash
# 完整的上传流程（首次）
pip install --upgrade build twine
rm -rf dist/ build/ *.egg-info
python -m build
twine check dist/*
twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ alayaflow
twine upload dist/*

# 更新版本
# 1. 更新 pyproject.toml 和 __init__.py 中的版本号
# 2. 然后运行：
rm -rf dist/ build/ *.egg-info
python -m build
twine check dist/*
twine upload dist/*
```

