[pyproject.toml 완전 정복 8편] 마이그레이션 전략 및 베스트 프랙티스

많은 Python 프로젝트가 여전히 setup.py, requirements.txt, MANIFEST.in 등 전통적 방식으로 관리되고 있습니다. 이러한 레거시 프로젝트를 모던 Python 패키징 표준인 pyproject.toml 기반으로 마이그레이션하면, 의존성 관리와 빌드/배포 과정이 단순화되고, CI/CD 파이프라인에서 재현성 높은 환경을 손쉽게 구축할 수 있습니다.

이번 글에서는 마이그레이션을 위한 단계별 접근 방법, 주의사항, 팀 내 합의 및 베스트 프랙티스 등을 제안합니다.

마이그레이션 전략

1단계: 기존 의존성, 메타데이터 파악

• setup.py의 setup() 함수 호출부를 살펴 이름, 버전, author, classifiers 등을 정리
• requirements.txt에서 런타임/개발 의존성을 분류
• MANIFEST.in 등 파일 패키징 관련 규칙 확인
• 이 정보를 바탕으로 pyproject.toml의 [project] 섹션에 name, version, authors, dependencies를 옮기고, optional-dependencies로 dev/docs 그룹 구성

2단계: 빌드 백엔드 결정

• 기존 setuptools 기반이라면 [build-system]에서 build-backend를 setuptools.build_meta로 명시
• 마이그레이션 시 조금 더 모던한 빌드 백엔드(예: Poetry, Flit, Hatch)로 전환 검토
• 팀원과 논의 후 프로젝트 규모, 필요 기능(가상환경 관리, 릴리즈 전략)에 맞는 빌드 백엔드 선택

3단계: 테스트 및 CI/CD 환경에서 검증

• 로컬에서 pip install . 또는 poetry install 명령으로 설치 테스트
• 기존 setup.py sdist bdist_wheel 명령 대신 poetry build나 python -m build로 wheel 빌드 확인
• CI 스크립트(예: GitHub Actions, GitLab CI) 수정: pyproject.toml 기반 의존성 설치(pip install --upgrade build 후 python -m build 또는 poetry install)로 변경
• 모든 테스트, 린터, 포매터 도구가 pyproject.toml 내 설정을 제대로 인식하는지 확인

4단계: 점진적 전환

• 처음부터 모든 설정을 한 번에 이전하기보다, 우선 빌드 시스템(build-system 섹션)과 핵심 의존성(dependencies)만 옮긴 뒤 프로젝트 동작 확인
• 이후 optional-dependencies, scripts, tool 설정(예: black, mypy) 순으로 단계적으로 이전
• 만약 팀원들이 Poetry CLI에 익숙지 않다면 문서화, 사내 위키, 코드 리뷰를 통해 사용법 공유

주의사항 및 베스트 프랙티스

1. 명확한 버전 범위 지정: dependencies에 버전 범위를 명확히 지정해 재현성 확보
2. optional-dependencies로 기능 모듈화: dev, docs, test 그룹을 만들어 필요할 때만 추가 의존성 설치 가능
3. readme, license, authors 정보 정리: [project] 섹션에 풍부한 메타데이터 제공, PyPI 사용자 경험 향상
4. CI에서 캐싱 전략: pyproject.toml 기반 빌드 시 의존성 설치를 캐시해 빌드 속도 단축
5. 도구별 문서 참고: Poetry, Flit, Hatch 공식 문서에서 pyproject.toml 예제 확인, 최신 PEP 동향 주시

마이그레이션 성공 사례

• 기존 setup.py로 작성된 라이브러리를 Poetry 기반 pyproject.toml로 전환 후, poetry lock으로 재현성 높은 빌드 보장, CI 파이프라인 안정화
• 다수의 도구 설정파일 제거하고 [tool.*] 섹션에 통합해 설정 파일 수 감소, 신규 개발자 온보딩 시 설정 이해도 향상

결론

• 마이그레이션은 초기 작업량이 들 수 있지만, 장기적으로 유지보수성과 빌드 파이프라인 안정성 향상
• 점진적 접근, 팀 내 교육, CI 환경 테스트를 통해 부담 줄이기 가능
• pyproject.toml 도입은 이제 파이썬 패키징의 사실상 표준이며, 새 프로젝트는 처음부터 pyproject.toml로 시작, 기존 프로젝트는 점진적 이전 권장

다음 글에서는 시리즈를 마무리하며, 전체 내용을 정리하고 추가 학습 자료, 더 나아갈 방향(고급 패키징 기법, 배포 전략 등)에 대해 소개하겠습니다.