Poetry는 Python 프로젝트의 설정을 관리하고, 의존성을 효과적으로 처리할 수 있도록 도와준다. 프로젝트를 초기화할 때, Poetry는 pyproject.toml 파일을 생성하여 프로젝트의 메타데이터와 설정을 기록한다. 이 파일은 프로젝트의 근간이 되며, Python 버전, 의존성, 빌드 시스템 등 다양한 설정을 포함한다.

pyproject.toml 파일의 역할

pyproject.toml 파일은 Poetry에서 중요한 역할을 한다. 이 파일은 Poetry뿐만 아니라 Python 생태계의 다른 도구들도 활용할 수 있는 표준 형식이다. 이 파일에는 프로젝트의 메타데이터, 의존성 정보, 빌드 옵션 등을 정의한다.

프로젝트 초기화 시 pyproject.toml 파일은 아래와 같은 기본 구조를 가지게 된다.

[tool.poetry]
name = "project_name"
version = "0.1.0"
description = ""
authors = ["Author Name <email@example.com>"]
license = "MIT"

[tool.poetry.dependencies]
python = "^3.8"

[tool.poetry.dev-dependencies]

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

이 기본 구조는 각 항목별로 의미를 가지고 있으며, 프로젝트 설정을 구체화하는 데 중요한 역할을 한다.

프로젝트 메타데이터 설정

프로젝트 이름과 버전

[tool.poetry] 섹션의 name과 version 항목은 프로젝트의 이름과 초기 버전을 정의한다. 예를 들어, 프로젝트 이름을 my_project로 하고, 버전을 0.1.0으로 설정할 수 있다.

[tool.poetry]
name = "my_project"
version = "0.1.0"

프로젝트 설명

description 필드는 프로젝트에 대한 간단한 설명을 담습니다. 이 필드는 필수는 아니지만, 특히 패키지를 PyPI(Python Package Index)에 배포할 경우 사용자에게 중요한 정보가 될 수 있다.

description = "This is a sample project using Poetry."

작성자 정보

프로젝트의 작성자는 authors 항목에 기록된다. 작성자의 이름과 이메일을 포함하며, 여러 명의 작성자를 명시할 수 있다.

authors = ["Your Name <your.email@example.com>"]

라이선스 설정

라이선스는 코드 사용 시 준수해야 할 규칙을 정의하는 중요한 요소이다. Poetry는 기본적으로 MIT 라이선스를 제안하지만, 프로젝트의 요구에 맞는 라이선스를 지정할 수 있다.

license = "MIT"

다른 라이선스 유형으로는 Apache, GPL 등이 있으며, 필요에 따라 적절한 라이선스를 선택할 수 있다.

Python 버전 설정

Poetry는 프로젝트에서 사용할 Python 버전을 명시적으로 지정할 수 있다. 이는 의존성 관리뿐만 아니라 가상 환경을 생성할 때에도 중요한 요소로 작용한다. pyproject.toml 파일의 [tool.poetry.dependencies] 섹션에서 python 항목을 사용하여 Python 버전을 정의한다. 예를 들어, Python 3.8 이상의 버전을 지원하는 경우 아래와 같이 설정한다.

[tool.poetry.dependencies]
python = "^3.8"

위 설정에서 ^3.8는 Python 3.8 이상의 마이너 버전(예: 3.9, 3.10)을 지원하지만, Python 4.0은 포함하지 않음을 의미한다.

의존성 정의

pyproject.toml의 [tool.poetry.dependencies] 섹션은 프로젝트의 의존성을 명시하는 곳이다. 의존성은 프로젝트를 실행하거나 테스트하는 데 필요한 외부 라이브러리나 패키지를 의미한다. 여기서는 패키지의 이름과 버전을 함께 정의할 수 있다.

예를 들어, requests 패키지의 버전을 2.25.1로 지정하고, flask 패키지를 최신 버전으로 설치하려면 아래와 같이 설정할 수 있다.

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

의존성을 정의할 때 버전 범위를 지정할 수 있다. 예를 들어, ^1.0은 1.x 버전 이상, 2.0 미만을 의미하며, 이는 Poetry가 의존성 충돌을 방지하기 위한 방식이다.

개발 의존성 설정

개발 환경에서만 필요한 의존성은 [tool.poetry.dev-dependencies] 섹션에 추가한다. 예를 들어, 테스트 프레임워크인 pytest와 코드 품질 도구인 black을 개발 의존성으로 추가할 수 있다.

[tool.poetry.dev-dependencies]
pytest = "^6.2"
black = "^21.5b1"

이와 같이 명시된 의존성은 실제 프로덕션 환경에서는 사용되지 않으며, 개발 및 테스트 환경에서만 사용된다.

빌드 시스템 설정

pyproject.toml 파일에서 [build-system] 섹션은 프로젝트를 빌드할 때 필요한 도구와 관련된 정보를 정의한다. Poetry는 poetry-core라는 빌드 백엔드를 사용하며, 이를 통해 프로젝트 패키징 및 배포를 관리한다.

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

이 섹션은 Poetry에서 기본적으로 설정해주는 부분이며, 사용자가 별도로 수정할 필요는 거의 없다. 그러나 패키징 방식에 따라 추가적인 설정이 필요할 수도 있다.

프로젝트 초기화 명령어

Poetry를 사용하여 새로운 Python 프로젝트를 초기화하는 명령어는 간단한다. 터미널에서 프로젝트 디렉토리로 이동한 후 아래 명령어를 실행하면, pyproject.toml 파일을 생성하여 프로젝트를 초기화할 수 있다.

poetry init

이 명령어는 대화형으로 프로젝트의 기본 설정을 안내하며, 이름, 버전, 의존성 등을 직접 입력할 수 있다. 만약 대화형 과정 없이 기본 설정으로 프로젝트를 초기화하고 싶다면 --no-interaction 옵션을 추가할 수 있다.

poetry init --no-interaction

이후, 프로젝트가 정상적으로 초기화되면 해당 디렉토리에 pyproject.toml 파일이 생성되고, 파일을 열어 수정할 수 있다.