python-project-standards

Python Project Standards

When to Load This Skill

Load when working with: pyproject.toml, Python files, pre-commit config, dependency management, type hints, linting configuration.

Stack Versions (as of 2026-Q1)

• Python: >=3.11 (minimum), prefer 3.12
• uv: latest stable (replaces pip, venv, pip-tools — all in one)
• Ruff: >=0.9.0
• MyPy: >=1.10.0
• pre-commit: >=3.7.0

pyproject.toml Standard Config

The canonical pyproject.toml for all projects. Copy and adjust [project].name and dependencies.

[project]
name = "project-name"
version = "0.1.0"
description = ""
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[project.optional-dependencies]
dev = [
    "ruff>=0.9.0",
    "mypy>=1.10.0",
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0",
    "pytest-bdd>=7.0.0",
    "pytest-cov>=5.0.0",
    "httpx>=0.27.0",
]

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

[tool.ruff]
target-version = "py311"
line-length = 100
fix = true

[tool.ruff.lint]
select = [
    "E",   "W",   # pycodestyle
    "F",          # pyflakes
    "I",          # isort
    "B",          # bugbear
    "C4",         # comprehensions
    "UP",         # pyupgrade
    "ANN",        # annotations
    "S",          # bandit security
    "SIM",        # simplify
    "TCH",        # type-checking imports
    "RUF",        # ruff-specific
]
ignore = ["ANN101", "ANN102", "S101"]

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["S101", "ANN"]

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
no_implicit_reexport = true
ignore_missing_imports = false

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under=80"

[tool.coverage.run]
source = ["src"]
omit = ["tests/*", "*/migrations/*"]

uv Commands Reference

uv init project-name
uv add fastapi uvicorn[standard]
uv add --dev ruff mypy pytest pytest-asyncio pytest-bdd
uv run pytest
uv run ruff check .
uv run mypy src/
uv sync
uv lock