Python Best Practice Checker

The Problem

Your Python module passes ruff, passes mypy, passes tests — and still has a mutable default argument that silently corrupts state between calls, a bare except clause that swallows interrupts, a regex recompiled inside a loop running 10K times per request, and unvalidated deserialization of user-supplied data. Linters check syntax and style. This skill checks the semantic patterns that cause production incidents.

What You Get

• PEP 8 style audit — naming conventions, import organization, line length, blank line rules, trailing whitespace, and file structure validation with exact line numbers and corrections
• Type annotation completeness — checks all function signatures for parameter types and return types, enforces modern Python 3.10+ syntax (union pipe instead of Union generics, builtin list/dict instead of typing imports), and flags overly broad Any usage
• Anti-pattern detection — mutable default arguments, bare except clauses, string concatenation in loops, for-range-when-enumerate-would-work, comprehension side effects, and module-level executable code
• Security vulnerability scan — dynamic code evaluation on user input, SQL string concatenation, hardcoded credentials, unsafe deserialization of untrusted data, and insecure temp file usage
• Performance pitfall identification — repeated attribute lookup in loops, unnecessary list materialization where generators suffice, re-compiling regex per call, and using list.pop(0) where deque is appropriate
• Severity-scored report — findings categorized as CRITICAL (security), ERROR (runtime failure), WARNING (anti-patterns), INFO (style), with corrected code examples for each finding

Why This Beats Prompting It Yourself

Ruff catches style violations. MyPy catches type mismatches. Neither catches that your function with a mutable default argument silently shares state across calls, that a bare except hides user interrupts, or that a file open call leaks the handle if reading raises. This skill performs a semantic audit that goes beyond what static analysis tools detect — checking the behavioral patterns that cause silent bugs, not just the syntactic rules that prevent them.

Example Session

You: "Audit this Python module for quality" (pastes 150-line module)

Agent: "Python Audit Report — payment_handler.py — Score: C (42 issues found)

CRITICAL (1):

• Line 89: Deserializes untrusted input with unsafe deserialization. Use json.loads() or msgspec instead.

ERROR (3):

• Line 23: Mutable default arguments (empty list, empty dict) shared across calls. Replace with None sentinel + in-function initialization.
• Line 67: Bare except with pass — swallows all exceptions including interrupts. Use specific exception types with logging.
• Line 112: File open not inside a context manager — handle leaks if reading raises.

WARNING (8):

• Line 34: for-range with len() — use enumerate() instead
• Line 56: Regex compiled inside loop — move to module-level constant
• Line 78: String concatenation in loop — use join()
• Line 91: Using typing.List/Dict imports — use builtin generics (Python 3.10+)

INFO (30): [style, naming, documentation findings]

Top 3 highest-impact fixes:

1. Replace unsafe deserialization with json (CRITICAL security)
2. Fix mutable default arguments (silent state corruption)
3. Wrap file I/O in context managers (resource leak)"

Use Cases

• Pre-commit quality gate to catch semantic issues that linters miss
• Code review for Python PRs where type hints and style are correct but behavior is subtly wrong
• Onboarding audit to establish a quality baseline on a new Python codebase
• Post-refactoring verification to ensure changes didn't introduce anti-patterns
• Security audit of Python code that handles user input or external data

Known Limitations

This skill is a heuristic audit — it complements but does not replace mypy, ruff, or pyright. Some findings may be false positives if the code uses patterns the skill doesn't recognize (dynamic metaclasses, clever init_subclass usage). Always check the project's pyproject.toml before recommending Python 3.10+ syntax — don't suggest modern syntax for a codebase targeting Python 3.9.