Python Best-Practices Skill

Idiomatic refactors and audits - an Agent Skill for Python 3.14 code quality.

What This Skill Does

Audits a package for idiomatic Python: ruff lint/format fixes, pathlib over os.path, dataclasses vs dicts, exception chaining, logging over print, security smells (eval, pickle, SQL f-strings), and produces tiered refactor PR plan.

When to Invoke

Legacy module before extraction to library
Pre-release security pass
Onboarding cleanup sprint on hot paths
PR feels "Java-ish" or non-idiomatic

Inputs

Input	Why
Target path	`src/billing/` scope
Risk tolerance	auto-fix safe vs manual review
Test presence	required before behavior-changing refactors
Style config	`ruff.toml` / `pyproject` tool section
Team rules	link to python-rules section ADRs

Outputs

ruff check --fix and ruff format diff summary
Markdown audit: critical / major / minor findings
Suggested ADR for patterns (Result type, DI, etc.)
Test gap list if coverage missing on changed modules
Verification command block

Guardrails

Tests green before and after - no drive-by behavior changes.
No mass rename without deprecation - public API semver.
Use raise ... from exc - preserve tracebacks.
Replace mutable default args - use None sentinel.
f-strings only - no % or .format in new edits.
Align with 50 Python Rules when org adopted.

Recipe

uv run ruff check src/ --fix
uv run ruff format src/
uv run pytest -q
uv run mypy src/  # optional gate

Working Example (fix mutable default)

# before
def add_item(item, bucket=[]):
    bucket.append(item)
    return bucket
 
# after
def add_item(item, bucket=None):
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket

FAQs

Auto-apply all ruff fixes?

Safe fixes only in first PR - unsafe rules need human review per file.

Black still needed?

ruff format replaces Black when enabled - one formatter per repo.

50 Python Rules Every Specialist Should Follow - rules
PEP 8 and Style Reference - style
Linting & Formatting - ruff setup
Refactoring Decisions - when to refactor

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Input

Why

Target path

src/billing/ scope

Risk tolerance

auto-fix safe vs manual review

Test presence

required before behavior-changing refactors

Style config

ruff.toml / pyproject tool section

Team rules

link to python-rules section ADRs

Guardrails

Tests green before and after - no drive-by behavior changes.

No mass rename without deprecation - public API semver.

Use raise ... from exc - preserve tracebacks.

Replace mutable default args - use None sentinel.

f-strings only - no % or .format in new edits.

Align with 50 Python Rules when org adopted.

# before def add_item(item, bucket=[]): bucket.append(item) return bucket # after def add_item(item, bucket=None): if bucket is None: bucket = [] bucket.append(item) return bucket

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Python Best-Practices Skill

Search Documentation

Python Best-Practices Skill