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

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

1. Tests green before and after - no drive-by behavior changes.
2. No mass rename without deprecation - public API semver.
3. Use raise ... from exc - preserve tracebacks.
4. Replace mutable default args - use None sentinel.
5. f-strings only - no % or .format in new edits.
6. 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

Related

• 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+.