python-dev

Modern Python Development

이 스킬은 Astral 툴체인 중심의 모던 Python 개발을 강제한다. Claude가 기본적으로 제안하는 pip, poetry 등의 구식 도구 대신, uv/ruff/ty 기반의 최신 워크플로우를 사용한다.

핵심 철학

1. Astral 툴체인 우선 — uv(패키지 관리), ruff(린터/포매터), ty(타입 체커)는 Rust로 작성되어 기존 도구 대비 10~100배 빠르다. 속도뿐 아니라 통합 경험이 핵심이다.
2. 완전한 타입 어노테이션 — 모든 함수 시그니처에 파라미터 타입과 리턴 타입을 선언한다. 타입 시스템은 런타임 버그를 컴파일 타임에 잡는 가장 효율적인 방법이다.
3. Python 3.12+ — 최신 문법을 적극 사용한다. type 키워드, X | None 유니온, 소문자 제네릭(list[str]) 등.
4. 단일 설정 파일 — 모든 도구 설정을 pyproject.toml에 통합한다. setup.py, setup.cfg, .flake8, .isort.cfg 등 개별 설정 파일을 만들지 않는다.

금지 도구 → 대체 매핑

이 도구들은 절대 사용하지 않는다. 대신 우측의 대체 도구를 사용한다.

금지	대체	이유
pip install	uv add	uv가 의존성 해결과 설치를 10배 이상 빠르게 수행
pip freeze > requirements.txt	uv.lock (자동 관리)	락 파일이 재현 가능한 빌드를 보장
poetry	uv	uv가 poetry의 모든 기능을 더 빠르게 제공
conda	uv	uv가 Python 버전 관리까지 통합
setup.py / setup.cfg	pyproject.toml	PEP 621 표준, 모든 도구가 지원
requirements.txt	pyproject.toml + uv.lock	선언적 의존성 + 결정적 락 파일
isort	ruff (I 규칙셋)	ruff가 isort 기능을 내장
flake8 / pylint	ruff	ruff가 대부분의 규칙을 통합
black (기본)	ruff format	ruff format이 black 호환 출력을 더 빠르게 제공. black은 ruff format이 부적절한 특수 경우에만 폴백으로 사용
virtualenv / venv	uv venv (자동)	uv가 가상환경을 자동 관리

프로젝트 초기화

새 프로젝트 생성

uv init <project-name>
cd <project-name>

빌드 백엔드 선택

PyPI 배포 라이브러리이면서 C 확장, 데이터 파일 포함, 커스텀 빌드 훅이 필요한가?
  YES → hatchling
  NO  → uv_build (기본값)

대부분의 프로젝트(웹 서비스, CLI 도구, 단순 라이브러리)는 uv_build를 사용한다. hatchling은 복잡한 빌드 요구사항이 있는 라이브러리에만 선택한다.

디렉토리 레이아웃

항상 src/ 레이아웃을 사용한다. 프로젝트 루트에서 패키지를 직접 import하는 실수를 방지한다.

project-name/
├── pyproject.toml
├── uv.lock
├── src/
│   └── package_name/
│       ├── __init__.py
│       ├── main.py
│       └── py.typed          # PEP 561 — 타입 정보 제공 마커
├── tests/
│   ├── conftest.py
│   └── test_main.py
└── .python-version           # uv가 자동 생성

pyproject.toml 전체 템플릿은 references/pyproject-templates.md를 참조하라.

타입 어노테이션 규칙

Python 3.12+ 문법을 사용한다. 이전 버전 호환 문법을 사용하지 않는다.

필수 규칙

• 모든 함수 파라미터와 리턴 타입을 선언한다.
• list, dict, tuple, set은 소문자로 사용한다 (from typing import List 금지).
• X | None을 사용한다 (Optional[X] 금지).
• collections.abc의 Sequence, Mapping, Iterable을 사용한다 (typing에서 import 금지).
• 복잡한 타입 별칭은 type 키워드를 사용한다 (Python 3.12+).
• Any 사용 시 주석으로 이유를 명시한다.

Before / After 예시

# BAD — 구식 타이핑, 리턴 타입 누락
from typing import Optional, List, Dict

def get_users(ids: Optional[List[int]] = None) -> Dict:
    ...

def process(data):
    return data.strip()

# GOOD — 모던 3.12+ 타이핑
from collections.abc import Sequence

type UserMap = dict[int, "User"]

def get_users(ids: list[int] | None = None) -> UserMap:
    ...

def process(data: str) -> str:
    return data.strip()

Pydantic 모델

API 데이터 구조는 Pydantic BaseModel로 정의한다. 딕셔너리를 직접 반환하지 않는다.

from pydantic import BaseModel, Field

class CreateJobRequest(BaseModel):
    model_config = {"strict": True}

    file_id: str = Field(description="업로드된 파일의 ID")
    presets: list[str] = Field(min_length=1, description="변환 프리셋 목록")
    mode: str = Field(default="crop", pattern=r"^(crop|padding|blur|stretch)$")

타입 체커 선택

프로젝트 복잡도에 따라 타입 체커를 선택한다.

단순 (단일 패키지, 적은 외부 의존성, 플러그인 불필요)
  → ty
  설치: uv add --dev ty
  실행: uv run ty check

중간 (FastAPI, SQLAlchemy, Pydantic, 다중 패키지)
  → pyright (strict mode)
  설치: uv add --dev pyright
  실행: uv run pyright

복잡 (모노레포, Django, 무거운 ORM, 다수의 타입 스텁 필요)
  → mypy (strict mode)
  설치: uv add --dev mypy
  실행: uv run mypy src/

ty는 Astral이 만든 신규 타입 체커로, 빠르고 가볍다. 아직 생태계 커버리지가 pyright/mypy보다 좁으므로 복잡한 프로젝트에서는 pyright를 권장한다.

각 타입 체커의 pyproject.toml 설정은 references/type-checking-guide.md를 참조하라.

린팅 & 포매팅

ruff가 린터와 포매터를 모두 담당한다.

기본 규칙셋

[tool.ruff.lint]
select = ["E", "F", "W", "I", "UP", "B", "SIM", "TCH", "RUF", "N", "S", "A", "C4", "DTZ", "T20", "PT", "RET", "ANN"]

규칙	역할
E/F/W	pycodestyle + pyflakes 기본
I	import 정렬 (isort 대체)
UP	모던 Python 문법 강제 (pyupgrade)
B	흔한 버그 패턴 감지
ANN	타입 어노테이션 강제
TCH	TYPE_CHECKING 블록 최적화
T20	print() 사용 금지
S	보안 취약점 감지

실행 순서

uv run ruff check --fix .    # 린트 + 자동 수정
uv run ruff format .          # 포매팅

전체 ruff 설정과 per-file-ignores는 references/ruff-config.md를 참조하라.

의존성 관리

# 의존성 추가
uv add fastapi uvicorn[standard]

# 개발 의존성 추가
uv add --dev pytest pytest-cov ruff pyright

# 의존성 제거
uv remove <package>

# 스크립트 실행 (가상환경 자동 활성화)
uv run python -m package_name
uv run pytest
uv run ruff check .

# Python 버전 고정
uv python pin 3.12

락 파일 관리

• uv.lock은 uv가 자동으로 관리한다. 수동 편집하지 않는다.
• uv.lock은 반드시 git에 커밋한다 (재현 가능한 빌드 보장).
• requirements.txt를 생성하지 않는다. CI에서도 uv sync를 사용한다.

테스팅

# 테스트 실행
uv run pytest

# 커버리지 포함
uv run pytest --cov=src --cov-report=term-missing

# 특정 테스트
uv run pytest tests/test_main.py -k "test_create"

테스트 구조

• 테스트 파일: test_<module>.py
• 공통 fixture: tests/conftest.py
• FastAPI 테스트: httpx.AsyncClient 사용
• pytest-asyncio로 async 테스트 지원 (asyncio_mode = "auto")

import pytest
from httpx import ASGITransport, AsyncClient

from package_name.main import app

@pytest.fixture
async def client() -> AsyncClient:
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as ac:
        yield ac

async def test_health(client: AsyncClient) -> None:
    response = await client.get("/health")
    assert response.status_code == 200

CLI 도구

CLI가 필요한 경우 typer를 사용한다. argparse, click 대신 타입 어노테이션 기반으로 CLI를 선언적으로 정의한다.

uv add typer

import typer

app = typer.Typer()

@app.command()
def process(
    input_file: str,
    output_dir: str = "output",
    verbose: bool = False,
) -> None:
    """파일을 처리한다."""
    if verbose:
        typer.echo(f"Processing {input_file}")
    ...

if __name__ == "__main__":
    app()

QA 체크리스트

코드를 커밋하기 전에 다음을 실행한다.

uv run ruff check --fix .         # 린트
uv run ruff format .              # 포맷
uv run pyright .                  # 타입 체크 (또는 ty check / mypy)
uv run pytest --cov=src           # 테스트

모든 명령이 에러 없이 통과해야 한다.

Reference 파일

필요할 때 다음 파일을 읽어 상세 설정을 확인하라.

파일	로드 시점
references/pyproject-templates.md	프로젝트 초기화 또는 pyproject.toml 수정 시
references/ruff-config.md	ruff 설정 추가/변경 또는 규칙 문제 해결 시
references/type-checking-guide.md	타입 체커 설정 또는 타입 에러 해결 시
references/fastapi-patterns.md	FastAPI 라우터, 모델, 서비스 작성 시