pyramidheadshark/.claude/skills/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

pre-commit Config Standard

See resources/pre-commit-config.md for the full .pre-commit-config.yaml.

Project File Structure

project-name/
├── src/
│   └── {project_name}/
│       ├── __init__.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── routers/
│       ├── core/
│       │   └── __init__.py
│       ├── services/
│       │   └── __init__.py
│       ├── adapters/
│       │   └── __init__.py
│       └── models/
│           └── __init__.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── unit/
│   ├── integration/
│   └── features/       # BDD .feature files
├── dev/
│   ├── status.md       # ALWAYS maintained
│   └── active/         # task-specific context
├── pyproject.toml
├── uv.lock
├── .pre-commit-config.yaml
├── .gitignore
├── .env.example
├── design-doc.md
└── README.md

.env.example Standard

Every project must have .env.example committed to repo with all required keys listed but no values. .env is always in .gitignore. Application validates all required env vars at startup via Pydantic BaseSettings.

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

    openrouter_api_key: str
    database_url: str
    environment: str = "development"


settings = Settings()

.gitignore Standard

See resources/gitignore.md for the full .gitignore template covering Python, uv, ML artifacts, IDE files.