Poetry를 사용하면 Python 프로젝트의 설정 및 의존성을 관리하는 데 매우 편리한 방법을 제공한다. 그 중심에는 pyproject.toml이라는 설정 파일이 있으며, 이 파일은 프로젝트의 메타데이터와 의존성을 정의하는 중요한 역할을 한다.

pyproject.toml 파일의 개요

pyproject.toml 파일은 Python 프로젝트의 설정 파일로, Poetry를 포함한 다양한 빌드 도구가 프로젝트를 관리하는 데 필요한 정보를 담고 있다. 이 파일은 프로젝트의 의존성 목록뿐만 아니라 프로젝트 자체에 대한 메타데이터도 포함하고 있다. pyproject.toml 파일은 표준화된 형식을 사용하여 빌드 시스템 간의 호환성을 높이고, 개발자가 Python 프로젝트를 더 쉽게 설정하고 유지 관리할 수 있도록 돕는다.

toml 형식

pyproject.toml 파일은 TOML(Tom's Obvious, Minimal Language)이라는 형식을 사용한다. TOML은 JSON이나 YAML과 비슷한 형식의 구성 파일 포맷으로, 직관적이고 간단한 문법을 가지고 있다. TOML 형식은 프로젝트 설정 파일에 자주 사용되며, 가독성이 좋고 구조화된 정보를 효율적으로 표현할 수 있다.

간단한 TOML 파일의 예시는 다음과 같다:

[tool.poetry]
name = "my_project"
version = "0.1.0"
description = "A simple example project"
authors = ["John Doe <john@example.com>"]

필수 섹션: [tool.poetry]

pyproject.toml 파일에서 가장 중요한 섹션 중 하나는 [tool.poetry] 섹션이다. 이 섹션은 프로젝트의 메타데이터를 정의하며, 다음과 같은 필드를 포함한다:

[tool.poetry]
name = "example_project"
version = "0.1.0"
description = "This is an example Python project managed by Poetry."
authors = ["Jane Doe <jane@example.com>"]

name

name 필드는 프로젝트의 이름을 정의한다. 이 이름은 나중에 PyPI(Python Package Index)에 패키지를 업로드하거나, 다른 프로젝트에서 이 프로젝트를 의존성으로 사용할 때 필요하다. 프로젝트 이름은 고유해야 하며, 일반적으로 소문자와 하이픈(-)을 사용해 명명하는 것이 좋다.

version

version 필드는 프로젝트의 버전을 나타낸다. 버전 번호는 일반적으로 세 가지 부분으로 나뉘는데, 예를 들어 1.2.3과 같은 형식이다. 이 형식은 Semantic Versioning을 따르는 경우가 많으며, 각각 다음과 같은 의미를 가진다:

description

description 필드는 프로젝트의 목적이나 주요 기능에 대한 간단한 설명을 제공한다. PyPI에 업로드할 경우, 이 설명은 사용자가 패키지를 검색할 때 패키지에 대한 요약 정보를 제공하는 데 사용된다.

authors

authors 필드는 프로젝트의 작성자를 정의하며, 작성자의 이름과 이메일을 포함할 수 있다. 여러 작성자가 있을 경우, 각 작성자를 따옴표 안에 쉼표로 구분해 나열할 수 있다.

authors = ["Jane Doe <jane@example.com>", "John Smith <john@example.com>"]

추가 메타데이터 필드

이 외에도 프로젝트의 더 많은 정보를 제공하기 위해 다음과 같은 추가 필드를 사용할 수 있다:

license = "MIT"
readme = "README.md"
homepage = "https://example.com"
repository = "https://github.com/example/example_project"
keywords = ["example", "poetry", "python"]

의존성 관리: [tool.poetry.dependencies]

프로젝트의 의존성은 [tool.poetry.dependencies] 섹션에서 관리된다. 이 섹션은 프로젝트가 실행되기 위해 필요한 Python 패키지들을 나열한다. 각 패키지는 이름과 버전이 지정되며, 특정 버전 범위를 설정할 수도 있다. 기본적으로 Poetry는 가장 최신의 안정된 버전을 설치하지만, 필요한 경우 특정 버전을 지정하거나 최소/최대 버전을 설정할 수 있다.

예시:

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.25.1"
flask = "^1.1.2"

버전 범위 지정

의존성의 버전은 다음과 같은 방식으로 범위를 지정할 수 있다:

[tool.poetry.dependencies]
numpy = ">=1.19.0, <1.20.0"

위의 예시는 numpy 패키지의 버전이 1.19.0 이상이고, 1.20.0 미만이어야 함을 의미한다.

개발 의존성 관리: [tool.poetry.dev-dependencies]

Poetry는 개발 환경에서만 필요한 의존성을 관리하기 위해 [tool.poetry.dev-dependencies] 섹션을 제공한다. 이 섹션은 프로덕션 코드에는 포함되지 않지만, 개발 과정에서 테스트나 디버깅에 필요한 패키지를 정의할 때 사용된다.

예를 들어, pytest와 같은 테스트 도구는 개발 환경에서만 사용되므로 dev-dependencies에 추가하는 것이 좋다.

[tool.poetry.dev-dependencies]
pytest = "^6.2"
black = "^21.4b2"

위 예시에서는 pytest와 black이 개발 환경에서만 필요한 의존성으로 정의되어 있다. 프로덕션 환경에서는 이 의존성들이 설치되지 않는다.

의존성 버전 제한 및 선택

Poetry는 의존성 버전 관리에서 유연한 옵션을 제공하여, 특정 버전 이상의 패키지를 요구하거나 메이저 업데이트를 피하면서도 최신 버전을 유지할 수 있게 한다. pyproject.toml 파일의 버전 규칙은 프로젝트의 안정성과 유지보수성을 높이는 데 중요한 역할을 한다.

버전 제한 연산자

예를 들어, 다음과 같은 설정은 특정 범위 내에서 최신 버전을 선택하게 만든다.

[tool.poetry.dependencies]
Django = "^3.2.0"

이 경우, Poetry는 Django의 메이저 버전이 3을 유지하는 한, 3.2.0 이상의 최신 버전을 설치한다.

선택적 의존성

Poetry는 선택적으로 설치할 수 있는 의존성도 정의할 수 있다. 이를 통해 프로젝트를 사용하는 개발자가 필요에 따라 추가적인 기능을 설치하도록 유도할 수 있다. 선택적 의존성은 [tool.poetry.dependencies] 섹션 내에서 정의되며, optional = true 옵션을 추가해 설정한다.

예시:

[tool.poetry.dependencies]
mysql-connector-python = { version = "^8.0", optional = true }

위 예시는 mysql-connector-python 패키지가 선택적임을 나타낸다. 이 패키지는 필요할 때만 설치할 수 있으며, 설치하지 않아도 기본적으로 프로젝트가 동작하는 데 문제가 없다.

Extras

Poetry는 extras 기능을 통해 선택적 의존성 그룹을 정의할 수 있다. 이는 선택적 의존성들을 그룹화하여 특정 상황에서 한 번에 설치할 수 있게 도와준다. 예를 들어, 데이터베이스와 관련된 패키지들을 하나의 그룹으로 묶어 필요할 때만 설치할 수 있게 할 수 있다.

[tool.poetry.extras]
db = ["mysql-connector-python", "psycopg2"]

위 예시는 db라는 이름의 extra를 정의하고, 이를 통해 mysql-connector-python과 psycopg2 패키지를 한 번에 설치할 수 있다. 사용자는 다음 명령어를 통해 이 패키지들을 설치할 수 있다.

poetry install --extras "db"

이를 통해, 프로젝트의 기본 의존성 외에도 선택적으로 추가 패키지를 쉽게 설치할 수 있다.

스크립트 정의: [tool.poetry.scripts]

Poetry를 통해 스크립트나 CLI(Command Line Interface) 명령어를 정의할 수도 있다. pyproject.toml 파일의 [tool.poetry.scripts] 섹션에 스크립트를 정의하면, 해당 명령어를 프로젝트의 가상 환경에서 간편하게 실행할 수 있다.

예시:

[tool.poetry.scripts]
my_script = "my_package.module:function"

위 설정에서는 my_script라는 명령어가 my_package.module의 function을 호출하도록 정의되었다. 이는 프로젝트 내에서 CLI 도구를 만들거나, 자주 사용하는 스크립트를 쉽게 실행할 수 있도록 한다.

빌드 시스템: [build-system]

pyproject.toml 파일의 마지막 중요한 섹션은 [build-system]이다. 이 섹션은 프로젝트가 어떻게 빌드될지에 대한 정보를 담고 있으며, Poetry가 빌드 시스템으로 설정되어 있어야 한다. 이를 통해 Poetry가 프로젝트의 의존성 설치 및 패키징을 관리할 수 있다.

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

이 섹션은 Poetry가 프로젝트의 빌드 및 배포를 원활하게 처리할 수 있게 해준다.