python-reviewer_skill

Overview

This skill reviews general Python code for style, type safety, idiomatic patterns, error handling, and documentation. It highlights PEP8 issues, missing or incorrect type hints, Pythonic anti-patterns, and risky error handling. Recommendations are practical and prioritized by severity to help developers improve maintainability and correctness.

How this skill works

I scan project files and common manifests (pyproject.toml, requirements.txt, setup.py) and inspect .py modules for style, typing, and runtime smells. Checks include line length, naming, import order, missing docstrings, type hint presence and specificity, mutable defaults, bare excepts, and opportunities for modern Python constructs. Results are grouped by category with file locations, severity, and actionable fixes.

When to use it

• General Python code reviews for libraries and applications
• Enforcing PEP8 and consistent style across a codebase
• Validating type hints and mypy/pyright readiness
• Detecting Pythonic idioms and mutable default risks
• Improving error handling and logging practices

Best practices

• Add type hints to all public APIs and prefer precise types over Any
• Use docstrings (Google or NumPy style) for modules, classes, and public functions
• Avoid mutable default arguments; use None and initialize inside the function
• Catch specific exceptions and log context; avoid bare except or broad Exception handlers
• Use modern Python syntax (X | Y unions, built-in generics, match) and leverage ruff/black/isort automation

Example use cases

• Run a full review on a Python package before release to catch style and typing gaps
• Audit a pull request to surface missing type annotations and exceptions handling issues
• Refactor legacy modules to replace mutable defaults and manual loops with comprehensions
• Validate a codebase for readiness with mypy/pyright and recommend fixes
• Provide a prioritized checklist of fixes (critical -> low) to guide maintainers