The pyproject.toml File

Python 프로젝트의 구성 정보와 빌드 시스템 요구 사항을 정의하는 표준화된 구성 파일.
TOML 형식을 사용하며 프로젝트의 메타데이터와 의존성을 중앙 집중적으로 관리한다.

주요 장점:

  • 특정 빌드 시스템에 종속되지 않는 표준화된 설정 파일.
  • TOML 형식을 사용하여 가독성이 높고 관리가 용이하다.
  • 프로젝트의 모든 설정을 한 곳에서 관리할 수 있어 편리하다.

pyproject.toml은 PEP 518, PEP 621 등의 파이썬 표준 제안에 의해 정의되었으며, 현대적인 파이썬 프로젝트 관리에 필수적인 요소로 자리잡고 있다.

역할

  1. 프로젝트 메타데이터 관리:
    - 프로젝트 이름, 버전, 설명, 저자 등의 기본 정보를 포함한다.
    - 라이선스, 키워드, 프로젝트 URL 등의 추가 정보도 저장할 수 있다.

  2. 의존성 관리:

    • 프로젝트에 필요한 라이브러리와 그 버전을 명시한다.
    • 개발 환경과 런타임 환경의 의존성을 분리하여 관리할 수 있다.

  3. 빌드 시스템 설정:

    • 프로젝트 빌드에 필요한 도구와 설정을 지정한다.
    • setuptools, poetry, flit 등 다양한 빌드 백엔드를 선택할 수 있다.

  4. 개발 도구 설정:

    • 테스트 프레임워크, 코드 포맷터, 린터 등의 개발 도구 설정을 포함할 수 있다.

  5. 패키지 구조 정의:

    • 프로젝트에 포함될 파일과 디렉토리를 지정할 수 있다.

  6. 스크립트 및 엔트리 포인트 정의:

    • 커맨드 라인 스크립트나 애플리케이션의 시작점을 설정할 수 있다.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

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

[project]
name = "example-project"
version = "1.0.0"
description = "An example Python project"
authors = [
    {name = "Example Author", email = "author@example.com"},
]
dependencies = [
    "requests>=2.28.0",
    "pandas>=1.4.0",
]

[tool.black]
line-length = 88
target-version = ["py37"]

[tool.isort]
profile = "black"
multi_line_output = 3

[tool.pytest.ini_options]
addopts = "-ra -q"
testpaths = ["tests"]

주요 섹션 설명

[build-system] 섹션

프로젝트의 빌드 시스템을 정의한다.
Poetry를 사용하여 프로젝트를 관리하는 경우, 다음과 같이 설정한다.

1
2
3

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

requires는 빌드에 필요한 패키지를 지정한다.
build-backend는 빌드 백엔드를 지정한다.

[project] 섹션

프로젝트의 이름, 버전, 설명, 저자 정보, 의존성 등 기본적인 메타데이터를 정의한다.
이를 통해 패키지의 배포 및 관리를 효율적으로 수행할 수 있다.

1
2
3
4
5
6

[project]
name = "example_project"
version = "0.1.0"
description = "An example Python project."
authors = [{name = "홍길동", email = "hong@example.com"}]
dependencies = ["requests>=2.25.1", "numpy>=1.19.5"]
  • name: 프로젝트의 이름을 지정.
  • version: 프로젝트의 버전을 지정.
  • description: 프로젝트에 대한 간단한 설명을 작성.
  • authors: 프로젝트의 저자를 명시.
  • dependencies: 프로젝트가 의존하는 패키지와 그 버전을 지정.

[tool] 섹션

Linter, type checker, formatter 등 다양한 개발 도구의 설정을 통합하여 관리할 수 있게 한다.

개발 환경 설정
1
2
3
4
5
6
7

[tool.black]
line-length = 88
target-version = ["py37"]

[tool.flake8]
max-line-length = 88
extend-ignore = "E203"
테스트 설정
1
2
3
4
5
6
7

[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-ra -q"
testpaths = [
    "tests",
    "integration",
]
Poetry

Poetry를 사용하여 프로젝트를 관리하는 경우, 다음과 같이 설정한다.

[tool.poetry] 섹션
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

[tool.poetry]
name = "my-package"
version = "0.1.0"
description = "A short description of the package."
authors = ["홍길동 <hong@example.com>"]

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

[tool.poetry.dev-dependencies]
pytest = "^6.2.2"

프로젝트의 메타데이터와 의존성을 정의

  • name: 프로젝트의 이름을 지정.
  • version: 프로젝트의 버전을 지정.
  • description: 프로젝트에 대한 간단한 설명을 작성.
  • authors: 프로젝트의 저자를 명시.
  • dependencies: 프로젝트가 의존하는 패키지와 그 버전을 지정.
  • dev-dependencies: 개발 환경에서만 필요한 의존성을 정의.
[tool.poetry.scripts] 섹션

설치 시 생성될 콘솔 스크립트를 정의한다.

1
2

[tool.poetry.scripts]
my-script = "my_package.module:main"

my-script라는 명령어를 생성하며, 이는 my_package.module 모듈의 main 함수를 실행한다.

[tool.poetry.extras] 섹션

선택적 의존성 그룹을 정의하여, 사용자가 필요에 따라 추가 기능을 설치할 수 있도록 한다.

1
2
3

[tool.poetry.extras]
mysql = ["mysqlclient"]
pgsql = ["psycopg2"]

사용자는 mysql 또는 pgsql 옵션을 선택적으로 설치할 수 있다.

[tool.poetry.urls] 섹션

프로젝트와 관련된 URL을 정의

1
2
3
4

[tool.poetry.urls]
homepage = "https://example.com"
repository = "https://github.com/example/my-package"
documentation = "https://example.com/docs"

참고 및 출처

pyproject.toml

The pyproject.toml file | Documentation | Poetry - Python dependency management and packaging made easy