s-canvas/UV_GUIDE.md

# uv 사용 가이드 — S-CANVAS

> **피드백 반영 (#5)**: pip 대신 uv 권장.
> uv = Rust로 작성된 ultra-fast Python 패키지 매니저. pip의 10~100배 빠름.

## 1. uv 설치 (Windows)

PowerShell:
```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

또는 (winget이 가능한 경우):
```powershell
winget install --id=astral-sh.uv -e
```

또는 pip로:
```powershell
pip install uv
```

설치 후 새 PowerShell 열고 확인:
```powershell
uv --version
```

## 2. 프로젝트 초기화

S-CANVAS 디렉토리에서:

```powershell
cd D:\2026\PROGRAM\1_S-CANVAS

# 기본 (Py3.9~3.12) 환경 만들기
uv venv .venv --python 3.11
.\.venv\Scripts\activate
uv pip install -e .

# 또는 Python 3.13 환경
uv venv .venv313 --python 3.13
.\.venv313\Scripts\activate
uv pip install -e ".[py313]"

# 개발 도구 함께 설치
uv pip install -e ".[py313,dev]"
```

## 3. uv lock — 재현 가능 환경

```powershell
uv lock           # uv.lock 생성/갱신 (의존성 트리 freeze)
uv sync           # uv.lock 기준으로 환경 동기화 (== install)
uv sync --frozen  # lock 변경 없이만 동기화 (CI 권장)
```

`uv.lock`은 git에 커밋 (다른 머신에서 동일 환경 재현).

## 4. 자주 쓰는 명령

| 작업 | uv 명령 | pip 등가 |
|---|---|---|
| 패키지 추가 | `uv pip install foo` | `pip install foo` |
| dev 패키지 추가 | `uv pip install -e ".[dev]"` | `pip install -e ".[dev]"` |
| 환경 동기화 | `uv sync` | `pip install -r requirements.txt` |
| 패키지 제거 | `uv pip uninstall foo` | `pip uninstall foo` |
| 의존성 트리 보기 | `uv pip tree` | `pip list` (트리는 pipdeptree) |
| 캐시 비우기 | `uv cache clean` | (없음) |

## 5. 기존 pip 환경에서 마이그레이션

기존 `venv313/`을 두고 새 `.venv313/`을 만들어 비교:

```powershell
uv venv .venv313 --python 3.13
.\.venv313\Scripts\activate
uv pip install -e ".[py313,dev]"

# import smoke test
python -c "import scanvas_maker; print('OK')"
```

문제 없으면 기존 `venv313/` 삭제. uv 환경이 더 빠르게 만들어짐 (수 초 vs 수 분).

## 6. CI/CD에서 uv 사용

Gitea Actions / GitHub Actions:
```yaml
- uses: astral-sh/setup-uv@v3
- run: uv sync --frozen --extra dev
- run: uv run pytest
- run: uv run ruff check
```

## 7. 기존 `requirements.txt` / `requirements-py313.txt` 호환

`pyproject.toml`이 정식 dependency 선언. 기존 requirements 파일들은:
- `requirements.txt`: 빌드 머신 핀 보존용 (PyInstaller .exe 재현)
- `requirements-py313.txt`: iter=3에서 만든 호환 핀 (현재는 `[py313]` extras에 흡수됨)

새 작업은 모두 `pyproject.toml` 수정. requirements.txt는 deprecated.

## 8. 트러블슈팅

### `uv pip install -e .` 실패: "build backend 'hatchling' not found"
```powershell
uv pip install hatchling
uv pip install -e .
```

### Python 3.13 wheel 못 찾음
일부 패키지(예: `rasterio`)는 3.13 wheel이 늦게 나올 수 있음. `[py313]` extras로 핀 완화.

### 기존 venv 충돌
```powershell
# 새 디렉토리로 venv 만들기
uv venv .venv-fresh --python 3.13
```

## 9. 사용자가 자주 하는 작업 (cheat sheet)

```powershell
# 처음 받은 직후
cd D:\2026\PROGRAM\1_S-CANVAS
uv venv .venv313 --python 3.13
.\.venv313\Scripts\activate
uv pip install -e ".[py313,dev]"

# 새 패키지 추가 시
uv pip install <package>
# pyproject.toml의 dependencies에도 수동 추가 후
uv lock

# 코드 작업 후 검사
ruff check
pytest

# 다른 머신에서 동일 환경 재현
git pull
uv sync --frozen
```