pyproject.toml

pyproject.toml — стандартный файл конфигурации проекта на Python, размещаемый в корне репозитория. В нём указываются система сборки пакета, его метаданные (имя, версия, зависимости, точки входа) и настройки инструментов разработки — линтеров, форматировщиков, тестовых фреймворков. Файл пришёл на смену разрозненным setup.py, setup.cfg, requirements.txt и множеству отдельных конфигов, объединив их в одном месте.

История

Долгое время пакет Python описывался исполняемым скриптом setup.py. Чтобы узнать хотя бы зависимости, нужно было запустить произвольный код, а сам скрипт требовал заранее установленного setuptools.

Стандартизация шла в несколько шагов:

Формат TOML выбран за простоту и однозначность; с Python 3.11 его чтение встроено в стандартную библиотеку (модуль tomllib).^[7]

Структура

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "weather-cli"
version = "0.3.0"
description = "Прогноз погоды в терминале"
readme = "README.md"
requires-python = ">=3.11"
license = "MIT"
authors = [{ name = "Иван Петров" }]
dependencies = [
    "httpx>=0.27",
    "rich>=13",
]

[project.optional-dependencies]
yaml = ["pyyaml>=6"]

[project.scripts]
weather = "weather_cli.main:run"

[dependency-groups]
dev = ["pytest>=8", "ruff"]

[tool.ruff]
line-length = 100

[tool.pytest.ini_options]
testpaths = ["tests"]

Таблицы

[build-system] сообщает установщику, какие пакеты поставить во временное окружение и какой бэкенд вызвать, чтобы собрать wheel или sdist. Благодаря этому pip может собрать любой проект, не зная, каким инструментом он сделан.

[project] — стандартные метаданные:^[1]

• name, version (или dynamic = ["version"], если версию вычисляет бэкенд, например из тега Git);
• dependencies — зависимости в формате спецификаторов версий;
• optional-dependencies — «экстра», устанавливаемые как pip install weather-cli[yaml];
• requires-python — поддерживаемые версии интерпретатора;
• scripts — консольные команды, создаваемые при установке;
• license — выражение SPDX (см. Лицензии ПО (MIT, GPL, Apache, CC)).

[dependency-groups] хранит зависимости, нужные только при разработке (тесты, линтеры, документация), — они не публикуются вместе с пакетом.

[tool.<имя>] — пространство для настроек сторонних инструментов: Ruff, pytest, mypy, coverage, Black и других. Каждый инструмент читает только свою таблицу.

Бэкенды сборки

Менеджеры проектов — Poetry, PDM, Hatch, uv — используют pyproject.toml как основной файл. Точные версии всего дерева зависимостей при этом хранятся отдельно, в файле блокировки (uv.lock, poetry.lock), который самим pyproject.toml не заменяется.

Типичные ошибки

• Указание зависимостей одновременно в pyproject.toml и requirements.txt с расхождениями.
• Отсутствие таблицы [build-system] — тогда инструменты по умолчанию предполагают setuptools.
• Жёсткая фиксация версий (==) в dependencies библиотеки: это мешает пользователям совмещать её с другими пакетами. Фиксируют версии приложения в файле блокировки, а в библиотеке задают диапазоны.

Аналоги

Похожую роль играют package.json в мире Node.js, Cargo.toml в Rust (см. Cargo и crates.io) и go.mod в Go (см. Go-модули (go.mod)).

См. также

• pip и PyPI
• uv (менеджер пакетов)
• Виртуальные окружения (venv)
• PEP

Источники

1. pyproject.toml specification — Python Packaging User Guide
2. PEP 518 — Specifying Minimum Build System Requirements
3. PEP 517 — A build-system independent format for source trees
4. PEP 621 — Storing project metadata in pyproject.toml
5. PEP 735 — Dependency Groups in pyproject.toml
6. TOML specification
7. tomllib — Parse TOML files