---
name: python-patterns-review
description: "Reviews Python code for typing, data modelling, exception handling, packaging, and test layout, with fixes that make it easier to read and safer to change. Use when a Python module or project needs a review of type hints, dataclass use, exception handling, packaging, and test structure. Do not use for debugging a specific failing test or converting a script into a web service. Related topics: coding, technical."
---

# Python Patterns Review

Reviews Python code for typing, data modelling, exception handling, packaging, and test layout, with fixes that make it easier to read and safer to change.

## When to use

Use this skill when a Python module or project needs a review of type hints, dataclass use, exception handling, packaging, and test structure. Do not use it for debugging a specific failing test or converting a script into a web service.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Skim the code and layout to note public functions, data shapes passed as dicts, try blocks, and where tests live.
3. Check typing on every public function and replace fixed-shape dicts with dataclasses or typed dictionaries where it clarifies intent.
4. Review each exception handler for specificity and useful messages, flagging bare excepts and silent passes.
5. Assess packaging and test layout against the selected focus areas and note gaps that block reuse or CI.
6. Write findings by impact with before and after snippets, then give a small-commit order for landing them.

## Inputs

- **The code** (longer free text)
- **Purpose** (free text, e.g. "What it does and who uses it")
- **Python version** (free text, e.g. "3.12")
- **Focus** (choose any: Type hints, Dataclasses, Exceptions, Packaging, Test layout, Async code, Dependencies)
- **Type checker in use** (choose one: mypy, pyright, None yet)

## Output

A findings list by impact with before and after snippets, then a numbered order of small commits for applying the changes.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Python Patterns Review

Review this Python code and show how to make it more idiomatic and maintainable.

- The code: {{The code}}
- Purpose: {{Purpose}}
- Python version: {{Python version}}
- Focus: {{Focus}}
- Type checker in use: {{Type checker in use}}

Begin with typing: public functions should have complete hints, dict-shaped data that has a fixed set of fields should become a dataclass or TypedDict, and Any should be rare and justified. Then exceptions: catch specific types, never a bare except, raise with a message that names the bad value, and define a small custom hierarchy only when callers need to tell cases apart. For packaging, check the project layout, entry points, pinned and unpinned dependencies, and whether a pyproject file is the single source of truth. For tests, check that they mirror the package, use fixtures instead of copied setup, and test behaviour rather than internals.

Present findings by impact with the line, the problem in a sentence, and a before and after snippet. Close with a short migration order so the changes can land as small commits.

## Pitfalls

- Adding type hints that the checker accepts but that describe the wrong shape, which hides bugs instead of catching them.
- Turning every dict into a dataclass, including ones that really are open-ended mappings.
- Wrapping a whole function in try and except Exception, so real failures look like normal returns.