# PyPI 배포 가이드

## 준비 단계

### 1. PyPI 계정 생성

1. **Test PyPI**: https://test.pypi.org/account/register/
2. **실제 PyPI**: https://pypi.org/account/register/

### 2. API 토큰 생성

- **Test PyPI**: https://test.pypi.org/manage/account/#api-tokens
- **실제 PyPI**: https://pypi.org/manage/account/token/

### 3. `~/.pypirc` 파일 설정

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

[pypi]
username = __token__
password = pypi-실제토큰여기

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-테스트토큰여기
```

권한 설정:
```bash
chmod 600 ~/.pypirc
```

## Test PyPI 배포 (필수!)

### 자동 배포

```bash
./scripts/deploy_test.sh
```

### 수동 배포

```bash
# 1. 이전 빌드 삭제
rm -rf dist/

# 2. 패키지 빌드
uv build

# 3. Test PyPI에 업로드
uv publish --publish-url https://test.pypi.org/legacy/
```

### 설치 테스트

```bash
# uvx로 테스트
uvx --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple \
    thetable-poc

# 또는 pipx로
pipx install --index-url https://test.pypi.org/simple/ \
    --pip-args='--extra-index-url https://pypi.org/simple' \
    thetable-poc
```

## 실제 PyPI 배포

⚠️ **주의**: 한 번 배포한 버전은 삭제하거나 수정할 수 없습니다!

### 자동 배포

```bash
./scripts/deploy_prod.sh
```

### 수동 배포

```bash
# 1. 이전 빌드 삭제
rm -rf dist/

# 2. 패키지 빌드
uv build

# 3. PyPI에 업로드
uv publish
```

### 배포 후 설치 확인

```bash
# uvx로 설치
uvx thetable-poc --help

# pipx로 설치
pipx install thetable-poc
thetable-poc --help
```

## 버전 업데이트

### 1. 버전 번호 규칙 (Semantic Versioning)

- `MAJOR.MINOR.PATCH` (예: `1.2.3`)
- **PATCH** (`0.1.0` → `0.1.1`): 버그 수정
- **MINOR** (`0.1.0` → `0.2.0`): 새로운 기능 (하위 호환)
- **MAJOR** (`0.1.0` → `1.0.0`): 주요 변경 (호환성 깨짐)

### 2. 버전 업데이트 절차

```bash
# 1. pyproject.toml 수정
sed -i 's/version = "0.1.0"/version = "0.1.1"/' pyproject.toml

# 2. 변경사항 커밋
git add pyproject.toml
git commit -m "chore: bump version to 0.1.1"

# 3. Git 태그 생성
git tag v0.1.1
git push origin main --tags

# 4. Test PyPI에 배포
./scripts/deploy_test.sh

# 5. 실제 PyPI에 배포
./scripts/deploy_prod.sh
```

## 배포 전 체크리스트

- [ ] `pyproject.toml`의 `authors` 이메일 수정
- [ ] `README.md`에 설치 방법 명시
- [ ] `LICENSE` 파일 존재
- [ ] 테스트 통과: `uv run pytest`
- [ ] 로컬 실행 확인: `uv run thetable-poc --help`
- [ ] `.gitignore`에 `dist/` 포함
- [ ] Test PyPI에서 먼저 테스트
- [ ] 버전 번호 확인 및 업데이트

## 문제 해결

### "File already exists" 에러

**원인**: 같은 버전을 재배포하려고 함

**해결**:
```bash
# pyproject.toml에서 버전 번호 올리기
version = "0.1.1"  # 0.1.0 → 0.1.1

# 다시 빌드 및 배포
rm -rf dist/
uv build
uv publish
```

### "Invalid or non-existent authentication" 에러

**원인**: API 토큰 설정 문제

**해결**:
1. `~/.pypirc` 파일 확인
2. API 토큰이 올바른지 확인
3. 파일 권한 확인: `chmod 600 ~/.pypirc`

### "Package name already exists" 에러

**원인**: PyPI에 이미 같은 이름의 패키지가 있음

**해결**:
```bash
# pyproject.toml에서 패키지 이름 변경
name = "thetable-poc-yourname"  # 고유한 이름으로 변경

# 다시 빌드 및 배포
rm -rf dist/
uv build
uv publish
```

### 의존성 설치 실패

**원인**: Test PyPI는 모든 패키지를 호스팅하지 않음

**해결**:
```bash
# Test PyPI와 실제 PyPI를 함께 사용
uvx --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple \
    thetable-poc
```

## CI/CD 자동화 (선택사항)

### GitHub Actions 예제

`.github/workflows/publish.yml`:

```yaml
name: Publish to PyPI

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Build package
        run: uv build

      - name: Publish to PyPI
        env:
          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
        run: uv publish
```

**설정**:
1. GitHub Repository Settings → Secrets → Actions
2. `PYPI_API_TOKEN`에 PyPI API 토큰 저장
3. 태그 푸시 시 자동 배포: `git tag v0.1.0 && git push --tags`

## 참고 자료

- [PyPI 공식 문서](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
- [uv publish 문서](https://docs.astral.sh/uv/guides/publish/)
- [Semantic Versioning](https://semver.org/)
