13장: Python 3.13 마이그레이션 실전 가이드

Python 3.9   - 보안 수정 종료: 2025년 10월
Python 3.10  - 보안 수정 종료: 2026년 10월
Python 3.11  - 보안 수정 종료: 2027년 10월
Python 3.12  - 보안 수정 종료: 2028년 10월
Python 3.13  - 보안 수정 종료: 2029년 10월

3.9  -> 3.10 -> 3.11 -> 3.12 -> 3.13
         |        |        |        |
         v        v        v        v
      패턴매칭  성능향상  타입문법  GIL제거
      테스트    테스트    테스트    테스트
 
각 단계에서:
1. CI에서 새 버전으로 테스트 실행
2. 경고와 에러 수정
3. 새 버전에서 안정성 확인
4. 프로덕션 배포

# 현재 Python 버전
python --version
 
# 설치된 패키지 목록
pip freeze > current_packages.txt
 
# 또는 uv 사용
uv pip freeze > current_packages.txt
 
# 의존성 트리 확인
uv tree

[project]
requires-python = ">=3.9"  # 이 값을 업데이트해야 함

1. distutils 완전 제거
   - setuptools로 대체
   - import distutils -> ModuleNotFoundError
   
2. unittest의 오래된 메서드 제거
   - assertEquals -> assertEqual
   - assertNotEquals -> assertNotEqual
   - assertRegexpMatches -> assertRegex
   
3. asyncio의 레거시 API 제거
   - asyncio.coroutine 데코레이터
   - loop 파라미터 (여러 함수에서)
   
4. imp 모듈 완전 제거
   - importlib으로 대체
   
5. typing의 일부 폐기
   - typing.Hashable -> collections.abc.Hashable
   - typing.Sized -> collections.abc.Sized

1. 여러 모듈에서 deprecated된 함수/클래스 제거
   - cgi, cgitb 모듈 제거
   - aifc, audioop, chunk, crypt, imghdr, mailcap 등 제거
   
2. typing 모듈 정리
   - typing.io, typing.re 네임스페이스 제거

# pyupgrade로 사용 가능한 업그레이드 확인
uvx pyupgrade --py312-plus src/**/*.py --check
 
# Ruff의 UP 규칙으로 업그레이드 기회 확인
uvx ruff check --select UP --target-version py312 src/
 
# vermin으로 최소 Python 버전 확인
uvx vermin src/

라이브러리          3.12    3.13    비고
-------------------------------------------------
Django            5.0+    5.1+    LTS 확인
FastAPI           0.109+  0.110+  최신 권장
Flask             3.0+    3.0+    
SQLAlchemy        2.0+    2.0+    
Pydantic          2.5+    2.6+    
NumPy             1.26+   2.0+    Major 변경 주의
pandas            2.1+    2.2+    
PyTorch           2.2+    2.3+    
Celery            5.3+    5.4+    
pytest            8.0+    8.0+    
requests          2.31+   2.31+   
httpx             0.27+   0.27+   

# 새 Python 버전으로 가상 환경 생성
uv venv --python 3.13 .venv-test
 
# 의존성 설치 시도
uv sync --python 3.13
 
# 설치 실패 시 어떤 패키지가 문제인지 확인
# uv가 에러 메시지에서 호환되지 않는 패키지를 알려줌

1. 패키지 업데이트
   - uv add "package>=새버전"
 
2. 대체 패키지 사용
   - 유지보수가 중단된 패키지는 대안을 찾음
 
3. 특정 패키지만 버전 고정
   - pyproject.toml에서 버전 범위를 조정
 
4. 패키지 기여
   - 오픈소스 패키지라면 3.13 호환성 PR 제출

# 변경 전 (Python 3.11 이하)
from distutils.core import setup
from distutils.util import strtobool
 
# 변경 후 (Python 3.12+)
from setuptools import setup
 
def strtobool(val: str) -> bool:
    """distutils.util.strtobool 대체"""
    val = val.lower()
    if val in ("y", "yes", "t", "true", "on", "1"):
        return True
    elif val in ("n", "no", "f", "false", "off", "0"):
        return False
    else:
        raise ValueError("invalid truth value " + repr(val))

# 변경 전
from typing import List, Dict, Tuple, Optional, Union, Set
 
def process(items: List[Dict[str, Any]]) -> Optional[Tuple[str, ...]]:
    result: Set[str] = set()
    ...
 
# 변경 후 (Python 3.12+)
def process(items: list[dict[str, Any]]) -> tuple[str, ...] | None:
    result: set[str] = set()
    ...

# 타입 힌트 현대화 (UP 규칙)
ruff check --select UP --fix --target-version py312 src/
 
# 임포트 정리
ruff check --select I --fix src/
 
# 전체 자동 수정
ruff check --fix src/
 
# 포매팅
ruff format src/

name: Test
on: [push, pull_request]
 
jobs:
  test:
    strategy:
      matrix:
        python-version: ["3.12", "3.13"]
        os: [ubuntu-latest, macos-latest]
 
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
 
      - name: Install uv
        uses: astral-sh/setup-uv@v4
 
      - name: Set up Python
        run: uv python install ${{ matrix.python-version }}
 
      - name: Install dependencies
        run: uv sync --all-groups
 
      - name: Run tests
        run: uv run pytest --tb=short -q
 
      - name: Run type checking
        run: uv run ty check src/
 
      - name: Run linting
        run: uv run ruff check src/

# 모든 경고를 에러로 처리하여 테스트
uv run python -W error::DeprecationWarning -m pytest
 
# 또는 경고만 표시
uv run python -W all -m pytest 2>&1 | grep DeprecationWarning

즉시 도입 (리스크 낮음):
  1. typing 임포트 현대화 (list, dict 소문자)
  2. Union -> | 연산자
  3. Ruff + uv 도구 전환
  4. f-string 유연한 문법 활용
 
중기 도입 (새 코드부터):
  5. PEP 695 타입 파라미터 문법
  6. type 문으로 타입 별칭
  7. override 데코레이터
  8. 패턴 매칭 (적합한 코드에서)
 
장기 검토:
  9. TypeIs, ReadOnly TypedDict
  10. free-threaded 모드 실험
  11. JIT 빌드 실험

[project]
name = "my-project"
version = "2.0.0"
requires-python = ">=3.12"
# 또는 3.13만 지원하는 경우
# requires-python = ">=3.13"
 
[tool.ruff]
target-version = "py312"  # 또는 "py313"
 
[tool.ruff.lint]
select = [
    "E", "W", "F", "I", "N",
    "UP",  # pyupgrade: 최신 문법 권장
    "B", "C4", "SIM", "RUF",
]
 
[tool.ty]
python-version = "3.12"  # 또는 "3.13"

패키지 관리:
  [ ] pip + virtualenv -> uv
  [ ] requirements.txt -> pyproject.toml + uv.lock
  [ ] pyenv -> uv python install
 
코드 품질:
  [ ] flake8 -> ruff check
  [ ] black -> ruff format
  [ ] isort -> ruff (I 규칙)
  [ ] mypy -> ty (또는 병행)
 
CI/CD:
  [ ] GitHub Actions에 uv 설정
  [ ] 멀티 Python 버전 테스트
  [ ] pre-commit 훅 업데이트

문제: ModuleNotFoundError: No module named 'distutils'
해결: pip install setuptools 또는 해당 import를 setuptools로 변경
 
문제: SyntaxWarning: invalid escape sequence
해결: 문자열의 백슬래시를 raw string(r"...")으로 변경하거나 이스케이프
 
문제: C 확장 빌드 실패
해결: 해당 패키지의 최신 버전으로 업그레이드
 
문제: typing 관련 ImportError
해결: typing에서 제거된 항목을 collections.abc 등으로 변경

# 경고 발생
pattern = "\d+"  # SyntaxWarning: invalid escape sequence '\d'
 
# 수정 방법 1: raw string 사용 (권장)
pattern = r"\d+"
 
# 수정 방법 2: 이중 백슬래시
pattern = "\\d+"

# Ruff의 W605 규칙으로 감지 및 수정
ruff check --select W605 --fix src/

소규모 프로젝트 (코드 5,000줄 이하):
  의존성 확인: 1시간
  코드 수정:  2~4시간
  테스트:    1~2시간
  총:       1일
 
중규모 프로젝트 (코드 5만줄 이하):
  의존성 확인: 2~4시간
  코드 수정:  1~2일
  테스트:    1일
  총:       3~5일
 
대규모 프로젝트 (코드 10만줄 이상):
  의존성 확인: 1일
  코드 수정:  1~2주
  테스트:    1주
  총:       2~4주