gh-physics91-claude-vibe/skills/python-reviewer/SKILL.md

---
name: python-reviewer
description: |
  WHEN: General Python code review, PEP8 compliance, type hints, Pythonic patterns
  WHAT: PEP8/style check + Type hint validation + Pythonic idioms + Error handling + Documentation
  WHEN NOT: FastAPI → fastapi-reviewer, Django → django-reviewer, Data science → python-data-reviewer
---

# Python Reviewer Skill

## Purpose
Reviews Python code for style, idioms, type safety, and best practices.

## When to Use
- Python code review requests
- PEP8 compliance check
- Type hint review
- "Is this Pythonic?" questions
- General Python project review

## Project Detection
- `requirements.txt`, `pyproject.toml`, `setup.py`, `setup.cfg`
- `.py` files in project
- `__init__.py` module structure

## Workflow

### Step 1: Analyze Project
```
**Python Version**: 3.11+
**Package Manager**: pip/poetry/uv
**Type Checking**: mypy/pyright
**Linter**: ruff/flake8/pylint
**Formatter**: black/ruff
```

### Step 2: Select Review Areas
**AskUserQuestion:**
```
"Which areas to review?"
Options:
- Full Python review (recommended)
- PEP8/Style compliance
- Type hints and safety
- Error handling patterns
- Performance and idioms
multiSelect: true
```

## Detection Rules

### PEP8 & Style
| Check | Recommendation | Severity |
|-------|----------------|----------|
| Line > 88 chars | Break line or refactor | LOW |
| Missing docstring | Add module/function docstring | MEDIUM |
| Import order wrong | Use isort or ruff | LOW |
| Inconsistent naming | snake_case for functions/vars | MEDIUM |

```python
# BAD: Inconsistent naming
def getUserName(userId):
    pass

# GOOD: PEP8 naming
def get_user_name(user_id: int) -> str:
    pass
```

### Type Hints
| Check | Recommendation | Severity |
|-------|----------------|----------|
| Missing return type | Add -> ReturnType | MEDIUM |
| Any type overuse | Use specific types | MEDIUM |
| Optional without None check | Add None handling | HIGH |
| Missing generic types | Use list[T], dict[K,V] | LOW |

```python
# BAD: No type hints
def process(data):
    return data.get("name")

# GOOD: Full type hints
def process(data: dict[str, Any]) -> str | None:
    return data.get("name")
```

### Pythonic Idioms
| Check | Recommendation | Severity |
|-------|----------------|----------|
| Manual loop for list | Use list comprehension | LOW |
| if x == True | Use if x | LOW |
| Manual dict iteration | Use .items(), .keys(), .values() | LOW |
| try/except pass | Handle or log exception | HIGH |
| Mutable default arg | Use None default | CRITICAL |

```python
# BAD: Mutable default argument
def append_to(item, target=[]):
    target.append(item)
    return target

# GOOD: None default
def append_to(item, target: list | None = None) -> list:
    if target is None:
        target = []
    target.append(item)
    return target

# BAD: Manual loop
result = []
for x in items:
    if x > 0:
        result.append(x * 2)

# GOOD: List comprehension
result = [x * 2 for x in items if x > 0]
```

### Error Handling
| Check | Recommendation | Severity |
|-------|----------------|----------|
| Bare except | Catch specific exceptions | HIGH |
| except Exception | Be more specific | MEDIUM |
| No logging in except | Add logging | MEDIUM |
| Missing finally | Add cleanup if needed | LOW |

```python
# BAD: Bare except
try:
    process()
except:
    pass

# GOOD: Specific exception with logging
try:
    process()
except ValueError as e:
    logger.error(f"Invalid value: {e}")
    raise
except IOError as e:
    logger.warning(f"IO error: {e}")
    return None
```

### Modern Python (3.10+)
| Check | Recommendation | Severity |
|-------|----------------|----------|
| Union[X, Y] | Use X \| Y | LOW |
| Optional[X] | Use X \| None | LOW |
| Dict, List from typing | Use dict, list builtin | LOW |
| No match statement | Consider match for complex branching | LOW |

```python
# OLD: typing imports
from typing import Optional, Union, List, Dict

def func(x: Optional[int]) -> Union[str, None]:
    pass

# MODERN: Built-in syntax (3.10+)
def func(x: int | None) -> str | None:
    pass

# Match statement (3.10+)
match status:
    case 200:
        return "OK"
    case 404:
        return "Not Found"
    case _:
        return "Unknown"
```

## Response Template
```
## Python Code Review Results

**Project**: [name]
**Python**: 3.11 | **Tools**: ruff, mypy, pytest

### Style & PEP8
| Status | File | Issue |
|--------|------|-------|
| LOW | utils.py:45 | Line exceeds 88 characters |

### Type Hints
| Status | File | Issue |
|--------|------|-------|
| MEDIUM | service.py:23 | Missing return type annotation |

### Pythonic Idioms
| Status | File | Issue |
|--------|------|-------|
| CRITICAL | models.py:12 | Mutable default argument |

### Error Handling
| Status | File | Issue |
|--------|------|-------|
| HIGH | api.py:67 | Bare except clause |

### Recommended Actions
1. [ ] Fix mutable default arguments
2. [ ] Add specific exception handling
3. [ ] Add type hints to public functions
4. [ ] Run ruff --fix for style issues
```

## Best Practices
1. **Type Hints**: Use for all public APIs
2. **Docstrings**: Google or NumPy style
3. **Error Handling**: Specific exceptions, always log
4. **Testing**: pytest with fixtures
5. **Tooling**: ruff (lint+format), mypy (types)

## Integration
- `fastapi-reviewer`: FastAPI specific patterns
- `django-reviewer`: Django specific patterns
- `python-data-reviewer`: Pandas/NumPy patterns
- `security-scanner`: Python security checks