python-tooling

Python Tooling (stack-agnostic)

pyproject.toml is the single source of truth for a modern Python project. Read it before doing anything else — it tells you the Python version, the package manager, the linting config, and the test settings.

Detection — which package manager is active

Check for lockfiles in this order:

test -f poetry.lock   && echo "Poetry"
test -f uv.lock       && echo "uv"
test -f Pipfile.lock  && echo "Pipenv"
test -f requirements.txt && echo "pip"

Signal	Package manager	Install command
poetry.lock	Poetry	poetry install
uv.lock	uv	uv sync
Pipfile.lock	Pipenv	pipenv install
requirements.txt only	pip	pip install -r requirements.txt

When only a pyproject.toml with a [build-system] section exists but no lockfile, check [build-system].requires to identify the build backend (setuptools, hatch, flit) and fall back to pip install -e ..

Always use the project's existing package manager. Do not mix managers (e.g., do not run pip install in a Poetry project).

pyproject.toml — canonical structure

A fully configured pyproject.toml for a PEP 621 project:

[project]
name = "myapp"
version = "0.1.0"
description = "Short project description"
requires-python = ">=3.10"
dependencies = [
    "httpx>=0.27",
    "pydantic>=2.6",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-cov>=5.0",
    "ruff>=0.4",
    "mypy>=1.10",
]

[project.scripts]
myapp = "myapp.cli:main"

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

[tool.ruff]
line-length = 88
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = ["E501"]

[tool.mypy]
python_version = "3.10"
strict = true
ignore_missing_imports = true

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

[tool.coverage.run]
source = ["src"]
branch = true

[tool.coverage.report]
fail_under = 80
show_missing = true