code-quality

Python Code Quality Skill

This skill sets up and enforces comprehensive Python code quality using a battle-tested toolchain. Based on real production Makefiles using uv for fast dependency management.

Philosophy

• Fast feedback: Use uv run and uvx for instant tool execution — no global installs
• Layered checks: Lint → Format → Typecheck → Complexity → Dead Code → File Length
• CI-ready: Every check is a Makefile target that returns non-zero on failure
• Opinionated defaults: Start strict, relax only with justification

---

Tool Stack

Tool	Purpose	Config Location
ruff	Linting + formatting (replaces flake8, isort, black)	pyproject.toml
mypy	Static type checking	pyproject.toml
xenon	Cyclomatic complexity gating	CLI flags
vulture	Dead code detection	CLI flags
pre-commit	Git hook automation	.pre-commit-config.yaml

---

Setup: pyproject.toml Configuration

When setting up code quality for a Python project, add these sections to pyproject.toml:

# =============================================================================
# Ruff — Linting & Formatting
# =============================================================================
[tool.ruff]
target-version = "py312"           # Adjust to project's minimum Python version
line-length = 120
src = ["src", "tests"]

[tool.ruff.lint]
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # pyflakes
    "I",      # isort (import sorting)
    "N",      # pep8-naming
    "UP",     # pyupgrade
    "B",      # flake8-bugbear
    "SIM",    # flake8-simplify
    "S",      # flake8-bandit (security)
    "A",      # flake8-builtins
    "C4",     # flake8-comprehensions
    "DTZ",    # flake8-datetimez
    "T20",    # flake8-print
    "PT",     # flake8-pytest-style
    "RET",    # flake8-return
    "PTH",    # flake8-use-pathlib
    "ERA",    # eradicate (commented-out code)
    "PL",     # pylint subset
    "RUF",    # ruff-specific rules
]
ignore = [
    "S101",   # assert usage (fine in tests)
    "PLR0913", # too many arguments (relax for data-heavy functions)
]

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101", "PLR2004", "T20"]  # Allow asserts, magic values, prints in tests

[tool.ruff.lint.isort]
known-first-party = ["PROJECT_NAME"]   # Replace with actual package name

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
line-ending = "lf"

# =============================================================================
# Mypy — Type Checking
# =============================================================================
[tool.mypy]
python_version = "3.12"               # Adjust to project's minimum Python version
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
strict_equality = true
warn_redundant_casts = true
warn_unused_ignores = true
no_implicit_reexport = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false          # Relax for test functions

# =============================================================================
# Pytest
# =============================================================================
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --strict-markers"
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
]