# Python Code Review

> Reviews Python code for type safety, async patterns, error handling, and common mistakes.

Reviews Python code for type safety, async patterns, error handling, and common mistakes. Use when reviewing .py files, checking type hints, async/await usage, or exception handling.

- Page: https://ss33.ai/skills/existential-birds/python-code-review-1641659570
- Publisher: existential-birds
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [Source control & code review](https://ss33.ai/skills/category/software-development-t44z8z/source-control-and-code-review-jebezw)
- License: Apache-2.0
- Source: https://github.com/existential-birds/beagle/blob/d1a74899fbfec74974d1818e4cac7c3d54d44b65/plugins/beagle-python/skills/python-code-review/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/existential-birds/python-code-review-1641659570

# Python Code Review

## Quick Reference

| Issue Type | Reference |
|------------|-----------|
| Indentation, line length, whitespace, naming | [references/pep8-style.md](references/pep8-style.md) |
| Missing/wrong type hints, Any usage | [references/type-safety.md](references/type-safety.md) |
| Blocking calls in async, missing await | [references/async-patterns.md](references/async-patterns.md) |
| Bare except, missing context, logging | [references/error-handling.md](references/error-handling.md) |
| Mutable defaults, print statements | [references/common-mistakes.md](references/common-mistakes.md) |

## Review Checklist

### PEP8 Style
- [ ] 4-space indentation (no tabs)
- [ ] Line length ≤79 characters (≤72 for docstrings/comments)
- [ ] Two blank lines around top-level definitions, one within classes
- [ ] Imports grouped: stdlib → third-party → local (blank line between groups)
- [ ] No whitespace inside brackets or before colons/commas
- [ ] Naming: `snake_case` for functions/variables, `CamelCase` for classes, `UPPER_CASE` for constants
- [ ] Inline comments separated by at least two spaces

### Type Safety
- [ ] Type hints on all function parameters and return types
- [ ] No `Any` unless necessary (with comment explaining why)
- [ ] Proper `T | None` syntax (Python 3.10+)

### Async Patterns
- [ ] No blocking calls (`time.sleep`, `requests`) in async functions
- [ ] Proper `await` on all coroutines

### Error Handling
- [ ] No bare `except:` clauses
- [ ] Specific exception types with context
- [ ] `raise ... from` to preserve stack traces

### Common Mistakes
- [ ] No mutable default arguments
- [ ] Using `logger` not `print()` for output
- [ ] f-strings preferred over `.format()` or `%`

## Valid Patterns (Do NOT Flag)

These patterns are intentional and correct - do not report as issues:

- **Type annotation vs type assertion** - Annotations declare types but are not runtime assertions; don't confuse with missing validation
- **Using `Any` when interacting with untyped libraries** - Required when external libraries lack type stubs
- **Empty `__init__.py` files** - Valid for package structure, no code required
- **`noqa` comments** - Valid when linter rule doesn't apply to specific case
- **Using `cast()` after runtime type check** - Correct pattern to inform type checker of narrowed type

## Context-Sensitive Rules

Only flag these issues when the specific conditions apply:

| Issue | Flag ONLY IF |
|-------|--------------|
| Generic exception handling | Specific exception types are available and meaningful |
| Unused variables | Variable lacks `_` prefix AND isn't used in f-strings, logging, or debugging |

## Gates (reporting workflow)

Complete **in order**. Do not advance until each **pass condition** is met.

1. **Scope** — **Pass:** You list every `.py` path (or explicit glob) you inspected this run.
2. **False-positive screen** — **Pass:** For each issue you plan to report, you checked **Valid Patterns** and **Context-Sensitive Rules** above; you drop or narrow the finding if those sections say not to flag it.
3. **Evidence** — **Pass:** Each remaining finding includes **`[FILE:LINE]`** (or a bounded line range). Symbols or short verbatim snippets may supplement the location anchor but do not replace it.
4. **Verification protocol** — **Pass:** You load [review-verification-protocol](../review-verification-protocol/SKILL.md) and complete its mandatory steps **for each reported issue** before the user-facing write-up.
5. **Ship** — **Pass:** The user-visible output matches whatever structure that protocol requires (no issues-only dump that skips its checks).

## When to Load References

- Reviewing code formatting/style → pep8-style.md
- Reviewing function signatures → type-safety.md
- Reviewing `async def` functions → async-patterns.md
- Reviewing try/except blocks → error-handling.md
- General Python review → common-mistakes.md

## Review Questions

1. Does the code follow PEP8 formatting (indentation, line length, whitespace)?
2. Are imports properly grouped (stdlib → third-party → local)?
3. Do names follow conventions (snake_case, CamelCase, UPPER_CASE)?
4. Are all function signatures fully typed?
5. Are async functions truly non-blocking?
6. Do exceptions include meaningful context?
7. Are there any mutable default arguments?

Before reporting: complete **Gates (reporting workflow)** above (especially gate 4).