[pyproject.toml 완전 정복 4편] 의존성 관리와 스크립트 정의

현대적인 파이썬 프로젝트에서 의존성 관리와 CLI 진입점(엔트리 포인트) 설정은 핵심적인 부분입니다. 이전에는 setup.py나 requirements.txt 등에 의존했지만, 이제 pyproject.toml의 [project] 섹션 내에서 정식 필드를 통해 의존성과 스크립트를 일관적으로 정의할 수 있습니다.

이번 글에서는 dependencies, optional-dependencies, scripts 필드를 자세히 살펴보고, 이를 통해 런타임 의존성, 선택적 의존성 그룹, 그리고 명령줄 스크립트를 어떻게 현대적이고 투명하게 관리할 수 있는지 알아봅니다.

[project.dependencies]로 런타임 의존성 정의

[project] 섹션 내 dependencies 필드는 패키지 런타임에 필요한 필수 의존성을 나열합니다. 버전 범위나 비교 연산자를 사용해 특정 범위의 패키지 버전만 허용할 수도 있습니다.

예:

[project]
name = "my_package"
version = "0.1.0"
dependencies = [
  "requests>=2.26.0,<3.0.0",
  "numpy>=1.20.0"
]

이렇게 하면 패키지를 설치하는 사용자는 my_package와 함께 requests, numpy가 자동으로 설치됩니다. 예전엔 setup.py의 install_requires나 requirements.txt로 관리하던 것을 이제 한곳에서 일관성 있게 처리합니다.

버전 규칙 및 호환성 전략

• requests>=2.26.0,<3.0.0 형태로 상한과 하한을 명시해 안정적인 호환성 확보
• 캐럿(^), 틸드(~) 표기 등 빌드 백엔드나 추가 도구(예: Poetry)에서 지원하는 버전 문법 활용 가능
• 프로젝트 규모 커질수록 명확한 버전 범위 지정이 안정적 배포에 도움

[project.optional-dependencies]로 선택적 기능 그룹 관리

[project.optional-dependencies]는 개발, 문서, 테스트, GPU 지원 등 특정 기능에 필요한 의존성 집합을 선택적으로 설치할 수 있게 합니다.

예:

[project.optional-dependencies]
dev = [
  "pytest",
  "mypy"
]
docs = [
  "sphinx"
]

이렇게 하면 pip install my_package[dev]로 개발 의존성 추가 설치 가능. 유저나 협업자가 필요한 기능별 의존성을 선택적으로 관리할 수 있으며, 패키지 기본 의존성은 가볍게 유지하고, 추가 기능은 필요할 때만 설치하는 유연한 전략을 구현할 수 있습니다.

[project.scripts]로 CLI 스크립트 정의

파이썬 패키지를 배포할 때 종종 명령줄 툴을 함께 제공하고 싶을 때가 있습니다. 이전에는 entry_points 등을 setup.py나 별도 필드에 정의했지만, 이제 pyproject.toml의 [project.scripts] 섹션을 통해 손쉽게 CLI 명령을 지정할 수 있습니다.

예:

[project.scripts]
mytool = "my_package.cli:main"

이렇게 하면 mytool 명령을 설치 시 $ mytool로 실행 가능. my_package/cli.py 안에 main() 함수를 정의해두면 해당 스크립트를 통해 CLI 인터페이스를 제공할 수 있습니다.

장점:

• 명령줄 진입점을 패키지 메타데이터와 동일한 파일에서 선언하므로 관리 용이
• 사용자에게 명령을 설치 즉시 사용할 수 있는 편의성 제공

단점:

• 명령명이 충돌할 수 있으니 이름 선정 시 주의 필요
• CLI 복잡도 커지면 CLI 프레임워크(Click, Typer)와 결합 고려

요약 및 장단점

• dependencies: 런타임 필수 의존성 일원화
• optional-dependencies: 기능별 옵션 의존성 그룹화, 설치자에게 선택권 부여
• scripts: CLI 명령 정의 간편화, setup.py의 entry_points보다 명확

장점:

• 한 파일(pyproject.toml)에서 의존성 및 스크립트 관리, 설정 일관성↑
• 기능별 의존성 구분으로 가볍고 탄력적인 설치 전략 수립 가능
• CLI 진입점 정의 간소화, 사용자 경험 개선

단점:

• 모든 빌드 백엔드나 인스톨러가 optional-dependencies를 동일하게 해석하지 않을 수도 있으므로 문서나 호환성 체크 필요
• CLI 복잡성 증가 시 별도 CLI 구성 전략 필요

이러한 방식으로 pyproject.toml을 활용하면, 의존성 관리부터 CLI 스크립트 정의까지 프로젝트 인스톨 경험을 체계적으로 개선할 수 있습니다.

다음 글에서는 [tool.*] 섹션을 통해 빌드 백엔드나 린터, 포매터 등 외부 도구 설정을 한 곳에 통합하는 방법을 다루며, pyproject.toml을 더욱 확장적으로 사용하는 전략을 소개하겠습니다.