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

For Poetry projects the structure differs slightly — dependencies live under [tool.poetry.dependencies] and scripts under [tool.poetry.scripts]. The [tool.ruff], [tool.mypy], and [tool.pytest.ini_options] sections are identical regardless of build backend.

ruff — lint and format

ruff replaces flake8, isort, pyupgrade, and black in a single fast tool. Configure it in pyproject.toml:

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

[tool.ruff.lint]
# E/F = pycodestyle + pyflakes, I = isort, UP = pyupgrade, B = bugbear, SIM = simplify
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = ["E501"]  # line-too-long — formatter handles this

[tool.ruff.lint.isort]
known-first-party = ["myapp"]

Key commands:

ruff check .            # lint — report issues
ruff check --fix .      # lint — auto-fix safe issues
ruff format .           # format — applies opinionated style (like black)
ruff format --check .   # format — exit non-zero if files would change (CI mode)

Run both in CI:

ruff format --check . && ruff check .

ruff's formatter is intentionally compatible with black's output — switching a black project to ruff format requires no manual changes.

mypy — type checking

Configure mypy in pyproject.toml:

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

strict = true enables a comprehensive set of checks including disallow_untyped_defs, warn_return_any, warn_unused_ignores, and others. Start with strict on new projects; on legacy projects enable checks incrementally.

Per-module overrides for third-party packages that ship without stubs:

[[tool.mypy.overrides]]
module = ["boto3.*", "botocore.*"]
ignore_missing_imports = true

Add a py.typed marker file to signal that your package ships inline type information:

touch src/myapp/py.typed

Then declare it in pyproject.toml:

[tool.hatch.build.targets.wheel]
include = ["src/myapp/py.typed"]

Run mypy:

mypy src/          # check all source files
mypy src/myapp/service.py   # check a single file

Virtual environments

Each package manager manages its own virtual environment:

# pip — manual venv
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
.venv\Scripts\activate         # Windows
pip install -e ".[dev]"

# Poetry — automatic venv
poetry install                 # creates .venv in project root (or in cache)
poetry shell                   # activate
poetry run pytest              # run without activating

# uv — automatic venv
uv sync                        # creates .venv and installs from uv.lock
uv run pytest                  # run without activating

# Pipenv — automatic venv
pipenv install --dev
pipenv shell
pipenv run pytest

Never commit the virtual environment. Add to .gitignore:

.venv/
__pycache__/
*.pyc
*.pyo
.mypy_cache/
.ruff_cache/
.pytest_cache/
dist/
*.egg-info/

Common commands — pip / Poetry / uv

Task	pip	Poetry	uv
Install all deps	pip install -r requirements.txt	poetry install	uv sync
Install dev deps	pip install -e ".[dev]"	poetry install --with dev	uv sync --extra dev
Add runtime dep	pip install X then freeze	poetry add X	uv add X
Add dev dep	pip install X then freeze	poetry add --group dev X	uv add --dev X
Remove dep	pip uninstall X then freeze	poetry remove X	uv remove X
Update dep	pip install -U X then freeze	poetry update X	uv lock --upgrade-package X && uv sync
Run script	python -m mymodule	poetry run python -m mymodule	uv run python -m mymodule
Run tool	ruff check .	poetry run ruff check .	uv run ruff check .
Show dep tree	pip list	poetry show --tree	uv tree

For pip projects, always regenerate the lockfile after adding or changing a dependency:

pip freeze > requirements.txt

Consider splitting into requirements.txt (runtime) and requirements-dev.txt (dev/test) to keep production images lean.

Console scripts

Define CLI entry points in pyproject.toml so users can run your tool by name after installation:

# PEP 621 / hatch / setuptools
[project.scripts]
myapp = "myapp.cli:main"
myapp-worker = "myapp.worker:run"

# Poetry
[tool.poetry.scripts]
myapp = "myapp.cli:main"

The value is "package.module:callable". The callable must accept no arguments (or parse sys.argv internally):

# src/myapp/cli.py
import argparse
import sys


def main() -> None:
    parser = argparse.ArgumentParser(description="myapp CLI")
    parser.add_argument("command", choices=["serve", "migrate"])
    args = parser.parse_args()
    match args.command:
        case "serve":
            from myapp.server import serve
            serve()
        case "migrate":
            from myapp.db import migrate
            migrate()
        case _:
            parser.print_help()
            sys.exit(1)

After installation (pip install -e . / poetry install / uv sync), the script is available on $PATH:

myapp serve
myapp migrate