비전공자 독학생의 파이썬 3.12 패키지 충돌 격파 및 클라우드 깃 세이브 전략

비전공자 독학생의 파이썬 3.12 패키지 충돌 격파 및 클라우드 깃 세이브 전략

FastAPI 교과서 예제를 공부하기 위해 소스코드를 무작정 실행했다가 빽빽한 에러 로그 앞에 멈춰 선 경험이 있을 것입니다. 본 포스팅에서는 파이썬 3.12 최신 환경에서 발생하는 레거시 패키지 버전 불일치 문제를 소스코드 수정 없이 인프라적으로 해결하고, 깃허브 코드스페이스(GitHub Codespaces) 내에서 버전 관리 시스템을 최적화하여 완벽한 세이브포인트를 박제한 여정을 공유합니다.

💡 핵심 요약: 소스코드를 고치지 않는 원칙을 고수하며 파이썬 3.12 호환 패키지 목록을 재구성하고, pip freeze 기법과 .gitignore 최적화를 통해 무결점 클라우드 깃(Git) 작업실을 완성했습니다.

1. 문제 상황: Python 3.12 환경의 버전 충돌 백태

책에 기록된 과거의 의존성 수첩(requirements.txt)을 그대로 설치한 채 서버 구동(python main.py)을 시도하자, 최신 파이썬 3.12 번역기 환경에서 호환되지 않는 레거시 문법 오류가 연쇄적으로 발생했습니다.

ImportError: cannot import name 'coroutine' from 'asyncio' ...
ImportError: email-validator version >= 2.0 required ...

이는 파이썬 3.12부터 asyncio.coroutine 문법이 완전히 삭제되면서, 책에 지정된 옛날 버전의 fastapi, motor, beanie 패키지들이 연쇄적으로 비명을 지른 결과였습니다.

2. 해결 과정: 소스코드를 건드리지 않는 인프라 튜닝

웹 에디터 상에서 제공되는 맞춤형 AI 비서(@Coach)와 워크스페이스 인스트럭션 가드레일을 활용하여, 소스코드를 난도질하는 대신 파이썬 3.12 버전에 최적화된 호환 라이브러리 목록을 새로 조합하여 일괄 클린 설치를 진행했습니다.

이어서 데이터베이스(MongoDB) 분리 가동을 위해 클라우드 터미널을 다중 개설하고, 도커 컴포즈(Docker Compose) 엔진으로 창고를 활성화한 뒤 네트워크 포트 정보 수첩(.env)을 매핑하여 마침내 Application startup complete 성공 신호를 받아냈습니다.

3. 클라우드 깃 최적화와 완벽한 박제 (Freeze & Amend)

성공적으로 구동을 완료한 직후, 매번 긴 패키지 목록을 수동으로 관리하는 번거로움을 해결하기 위해 현재 가상환경 상태를 그대로 촬영하여 덮어씌우는 pip freeze 마법을 발동했습니다.

# 현재 성공한 가상환경 패키지 버전을 requirements.txt에 영구 박제
pip freeze > requirements.txt

이 과정에서 파이썬 번역기가 실시간 연산을 위해 자동으로 구워내는 캐시 파편(.pyc 파일)들이 자꾸 Git 세이브 목록(Changes)을 더럽히는 현상을 발견했습니다. 이를 해결하기 위해 블랙리스트 수첩인 .gitignore에 포괄적 무시 규칙을 한 줄 추가하여 영구적으로 깨끗한 작업실을 구축했습니다.

# .gitignore 파일에 추가하여 컴파일 찌꺼기 폴더를 통째로 무시
__pycache__/

최종적으로 깃의 수정 세이브 기능(Amend)을 통해 불필요한 흔적 없이 깨끗하게 세이브포인트를 클라우드 깃 저장소에 안착시켰습니다.

4. 마치며: 사양과 장소에서 해방된 클라우드 네이티브 학습

이 과정을 통해 구축된 깃허브 코드스페이스 기반 실습실은 내 컴퓨터(맥북/맥미니)의 하드웨어 사양이 기본형이든 최신형이든 무관하게 언제 어디서나 인터넷만 연결되면 동일한 초고속 환경을 보장합니다. 인프라 스트레스에서 완전히 해방되었으니, 이제 진정한 탑다운(Top-Down) 방식으로 API 문서 자동화 화면(Swagger UI)을 종횡무진하며 백엔드 서비스 개발의 본질을 지치지 않고 독학해 나갈 것입니다!