Python 개발

# Python 개발

최신 도구인 uv, PEP 723, pytest 모범 사례를 사용하여 Python 스크립트, FastAPI 서비스, 테스트 스위트를 구축하세요.

10분 만에 테스트가 포함된 FastAPI 서비스를 구축할 수 있습니다.

## 이 플러그인의 기능

전체 Python 백엔드 워크플로우를 다루는 세 가지 스킬:

| 스킬 | 용도 |
|-------|---------|
| **Python 스크립팅** | uv와 PEP 723 인라인 의존성을 사용하는 독립형 스크립트 — virtualenv 설정 불필요 |
| **FastAPI 마스터리** | 라우팅, 요청 유효성 검사, 미들웨어, 인증, 데이터베이스 통합이 포함된 REST API 생성 |
| **pytest 마스터리** | 픽스처, 매개변수화, 모킹, 비동기 테스트, 커버리지를 포함한 테스트 스위트 |

## 완전한 예제: 테스트가 포함된 URL 단축 API 구축

### 1단계: FastAPI 서비스 스캐폴딩

```
다음 기능이 포함된 FastAPI URL 단축 서비스 생성:
- POST /shorten — {"url": "https://..."}을 수락하고 {"short_code": "abc123", "short_url": "http://localhost:8000/abc123"} 반환
- GET /{short_code} — 원본 URL로 리디렉션
- GET /stats/{short_code} — 클릭 수 반환
- 저장소로 SQLAlchemy를 통한 SQLite 사용
- 입력 유효성 검사 추가: 잘못된 URL 거부, 최대 URL 길이 2048
- 적절한 오류 응답 포함 (알 수 없는 코드의 경우 404, 잘못된 입력의 경우 422)
```

### 2단계: 포괄적인 테스트 추가

```
URL 단축기를 위한 pytest 테스트 작성:
- 유효한 URL로 POST /shorten 테스트 - 201 + short_code 반환
- 잘못된 URL로 POST /shorten 테스트 - 422 반환
- GET /{short_code} 올바른 리디렉션 테스트 (상태 307)
- 알 수 없는 코드로 GET /{short_code} 테스트 - 404 반환
- GET /stats/{short_code}가 여러 방문 후 올바른 클릭 수 반환 테스트
- 테스트 클라이언트로 httpx AsyncClient 사용
- 별도의 테스트 데이터베이스 사용 (메모리 내 SQLite)
- 다음을 위한 픽스처 추가: 앱 클라이언트, 샘플 단축 URL, 데이터베이스 설정/해제
```

### 3단계: 유틸리티 스크립트 추가

```
PEP 723 인라인 의존성이 포함된 Python 스크립트 생성:
- URL의 CSV 파일 읽기 (한 줄에 하나)
- 각 URL에 대해 /shorten 엔드포인트 호출
- original_url, short_url, short_code 열이 포함된 새 CSV 출력
- 의존성 관리를 위해 uv 사용 (httpx, csv는 의존성)
- 실패한 요청에 대한 재시도 논리 추가
- URL을 단축하지 않고 유효성을 검사하는 --dry-run 플래그 포함
```

**결과:** 완전한 테스트된 API 서비스 + 배치 유틸리티 스크립트 — 모두 자연어 프롬프트에서 생성되며 배포 준비 완료.

## 환경 요구사항

- **Python 3.10+** (3.12 권장)
- 빠른 의존성 해결을 위한 **uv** 패키지 관리자:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- FastAPI 프로젝트의 경우 의존성은 `pyproject.toml` 또는 `requirements.txt`를 통해 관리됩니다.
- 독립형 스크립트의 경우 PEP 723 인라인 메타데이터를 사용하면 스크립트 파일에 의존성을 직접 선언할 수 있습니다 — 별도의 설정 불필요

### 빠른 확인

```bash
python3 --version   # 3.10+
uv --version        # 최신 버전
```

## 오류 처리

### uv가 설치되지 않음

```
command not found: uv
```
**해결 방법:** uv 설치: `curl -LsSf https://astral.sh/uv/install.sh | sh`
또는 pip로 대체: `pip install -r requirements.txt`

### 테스트에서 가져오기 오류

```
ModuleNotFoundError: No module named 'httpx'
```
**해결 방법:** 테스트 의존성 설치: `uv pip install httpx pytest pytest-asyncio`

### FastAPI 서버가 시작되지 않음

일반적인 원인:
- 포트가 이미 사용 중: `uvicorn app:app --port 8001`
- 의존성 누락: `uv pip install fastapi uvicorn sqlalchemy`
- Python 버전이 너무 오래됨: 3.10+로 업그레이드

### pytest 픽스처를 찾을 수 없음

`fixture not found` 오류로 테스트가 실패하면 다음을 확인하세요:
- `conftest.py`가 테스트 디렉토리에 있는지
- 픽스처 함수가 `@pytest.fixture`로 장식되어 있는지
- 비동기 픽스처가 `@pytest_asyncio.fixture`를 사용하는지