Skip to content
Skills Library
Programming · Review & audit

Python Code Review with Modern Typing

/Python Code Review with Modern Typing

Review Python code ensuring strict type safety with Python 3.12+ conventions. Use when reviewing Python code, writing new Python code, or refactoring existing Python code.

Repository
faire ↗
Licence
MIT
Last repository change
25.07.2026

Assessment and security

90/ 100Class: good
Format15 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
3
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: examples/example-1-mixed-syntax/input.py, examples/example-2-untyped-code/input.py, examples/example-3-complex-generics/input.py

What it does and when to use it

Review Python code ensuring strict type safety with Python 3.12+ conventions. Use when reviewing Python code, writing new Python code, or refactoring existing Python code.

Original author description

Review Python code ensuring strict type safety with Python 3.12+ conventions. Use when reviewing Python code, writing new Python code, or refactoring existing Python code.

How it works

  1. Overview
  2. When to Use
  3. Process
  4. Examples
  5. Anti-patterns
  6. Testing This Skill
Original SKILL.md headings · 307 lines, 1,076 words
SKILL.md preview
---
name: Python Code Review with Modern Typing
description: Review Python code ensuring strict type safety with Python 3.12+ conventions. Use when reviewing Python code, writing new Python code, or refactoring existing Python code.
---

# Python Code Review with Modern Typing

## Overview

This skill provides systematic Python code review with emphasis on Python 3.12+ type annotations. It enforces strict typing and built-in generic types (`list`, `dict`, `type`) instead of deprecated `typing` equivalents (`List`, `Dict`, `Type`).

**Scope**: This skill focuses exclusively on type annotations, not code logic, design patterns, performance, or general quality.

## When to Use

- Reviewing pull requests containing Python code
- Writing new Python functions, classes, or modules
- Refactoring existing Python code to modern standards
- Conducting code audits for type safety
- Before merging Python code to main branch

## Process

Focus only on type annotation issues.

### 1. Type Annotation Audit

Check every function, method, and variable for proper type annotations:

```python
# ✅ CORRECT - Modern Python 3.12 syntax
def process_items(items: list[str], count: int) -> dict[str, int]:
    result: dict[str, int] = {}
    for item in items[:count]:
        result[item] = len(item)
    return result

# ❌ INCORRECT - Missing types
def process_items(items, count):
    result = {}
    for item in items[:count]:
        result[item] = len(item)
    return result

# ❌ INCORRECT - Old typing module syntax
from typing import List, Dict

def process_items(items: List[str], count: int) -> Dict[str, int]:
    ...
```

**Required checks:**
- [ ] All function parameters have type annotations
- [ ] All function return types are annotated (use `-> None` if no return)
- [ ] All class attributes have type annotations
- [ ] Complex variables have inline type annotations
- [ ] No imports from `typing` for `List`, `Dict`, `Set`, `Tuple`, `Type`

### 2. Built-in Generic Types

Verify usage of built-in generics instead of `typing` module equivalents:

**Use these (Python 3.12+):**
- `list[T]` not `List[T]`
- `dict[K, V]` not `Dict[K, V]`
- `set[T]` not `Set[T]`
- `tuple[T, ...]` not `Tuple[T, ...]`
- `type[T]` not `Type[T]`

**Import from typing:**
- `Any`, `Optional`, `Union`, `Callable`, `Protocol`, `TypeVar`, `Generic`
- `Literal`, `TypedDict`, `NotRequired`, `Required`
- `overload`, `final`, `override`

```python
# ✅ CORRECT - Modern syntax
from typing import Protocol, TypeVar

T = TypeVar('T')

class Container(Protocol):
    def get_items(self) -> list[str]: ...

def merge_dicts(a: dict[str, int], b: dict[str, int]) -> dict[str, int]:
    return {**a, **b}

# ❌ INCORRECT - Old typing module imports
from typing import List, Dict, Protocol

def merge_dicts(a: Dict[str, int], b: Dict[str, int]) -> Dict[str, int]:
    return {**a, **b}
```

### 3. Optional and Union Types

Check for proper use of modern union syntax:

```python
# ✅ CORRECT - Python 3.10+ union syntax
def find_user(user_id: int) -> dict[str, str] | None:
    return users.get(user_id)

def process(value: int | str | float) -> str:
    return str(value)

# ❌ INCORRECT - Old Optional/Union syntax
from typing import Optional, Union

def find_user(user_id: int) -> Optional[dict[str, str]]:
    return users.get(user_id)

def process(value: Union[int, str, float]) -> str:
    return str(value)
```

### 4. Type Completeness Check

Ensure no untyped code exists:

**Check these locations:**
- Function signatures (parameters and returns)
- Lambda expressions (where possible)
- Class attributes and properties
- Module-level variables
- Generator and comprehension expressions (when complex)

```python
# ✅ CORRECT - Fully typed
class UserService:
    _cache: dict[int, str]

    def __init__(self, cache: dict[int, str] | None = None) -> None:
        self._cache = cache or {}

    def get_user(self, user_id: int) -> str | None:
        return self._cache.get(user_id)

# ❌ INCORRECT - Untyped attribute
class UserService:
    def __init__(self, cache=None):
        self._cache = cache or {}

    def get_user(self, user_id):
        return self._cache.get(user_id)
```

### 5. Type Checking Validation

Run static type checker:

```bash
mypy --strict your_module.py
```

Configure in `pyproject.toml`:
```toml
[tool.mypy]
strict = true
python_version = "3.12"
```

### 6. Review Checklist

- [ ] No imports of `List`, `Dict`, `Set`, `Tuple`, `Type` from `typing`
- [ ] All functions have parameter and return type annotations
- [ ] All class attributes are typed
- [ ] Union types use `|` syntax, not `Union[]`
- [ ] Optional types use `X | None`, not `Optional[X]`
- [ ] Complex nested types are properly annotated
- [ ] `mypy --strict` passes without errors
- [ ] No `# type: ignore` comments without justification

## Examples

### Example 1: API Handler Review

**Before (❌):**
```python
from typing import Dict, List, Optional

def get_users(limit=10, offset=0):
    users = fetch_from_db(limit, offset)
    return {"users": users, "count": len(users)}

def create_user(data):
    user_id = save_to_db(data)
    return {"id": user_id}
```

**After (✅):**
```python
from typing import TypedDict

class UserResponse(TypedDict):
    users: list[dict[str, str]]
    count: int

class CreateResponse(TypedDict):
    id: int

def get_users(limit: int = 10, offset: int = 0) -> UserResponse:
    users: list[dict[str, str]] = fetch_from_db(limit, offset)
    return {"users": users, "count": len(users)}

def create_user(data: dict[str, str]) -> CreateResponse:
    user_id: int = save_to_db(data)
    return {"id": user_id}
```

### Example 2: Data Processing Pipeline

**Before (❌):**
```python
from typing import List, Dict, Callable

def transform_data(data, transformers):
    result = []
    for item in data:
        for transformer in transformers:
            item = transformer(item)
        result.append(item)
    return result
```

**After (✅):**
```python
from typing import Callable, TypeVar

T = TypeVar('T')

def transform_data(
    data: list[T],
    transformers: list[Callable[[T], T]]
) -> list[T]:
    result: list[T] = []
    for item in data:
        for transformer in transformers:
            item = transformer(item)
        result.append(item)
    return result
```

### Example 3: Class with Type Parameters

**Before (❌):**
```python
from typing import Generic, TypeVar, List, Optional

T = TypeVar('T')

class Container(Generic[T]):
    def __init__(self):
        self._items = []

    def add(self, item):
        self._items.append(item)

    def get_all(self):
        return self._items
```

**After (✅):**
```python
from typing import Generic, TypeVar

T = TypeVar('T')

class Container(Generic[T]):
    _items: list[T]

    def __init__(self) -> None:
        self._items = []

    def add(self, item: T) -> None:
        self._items.append(item)

    def get_all(self) -> list[T]:
        return self._items
```

## Anti-patterns

- ❌ **Don't**: Import `List`, `Dict`, `Set`, `Tuple`, `Type` from `typing` module
  - ✅ **Do**: Use built-in `list`, `dict`, `set`, `tuple`, `type` with generic syntax

- ❌ **Don't**: Use `Optional[X]` or `Union[X, Y]` syntax
  - ✅ **Do**: Use `X | None` and `X | Y` union syntax

- ❌ **Don't**: Leave any function, method, or class attribute untyped
  - ✅ **Do**: Add complete type annotations everywhere

- ❌ **Don't**: Use `# type: ignore` without explanation
  - ✅ **Do**: Fix the type issue or document why it's necessary

- ❌ **Don't**: Use `Any` as a shortcut to avoid thinking about types
  - ✅ **Do**: Define proper types even if they're complex

- ❌ **Don't**: Skip type annotations on simple functions
  - ✅ **Do**: Type everything, even trivial functions

- ❌ **Don't**: Mix old and new typing syntax in the same codebase
  - ✅ **Do**: Consistently use Python 3.12+ syntax throughout

## Testing This Skill

Follow instructions in `examples/EXAMPLES.md`.

---

**Remember**: No untyped code. Use Python 3.12+ built-in generics. Type everything.
Files in this package (11)
  • SKILL.md 8 KB
  • examples/EXAMPLES.md 1 KB
  • examples/example-1-mixed-syntax/expected.md 2 KB
  • examples/example-1-mixed-syntax/input.py 1 KB
  • examples/example-1-mixed-syntax/scenario.md 1 KB
  • examples/example-2-untyped-code/expected.md 2 KB
  • examples/example-2-untyped-code/input.py 1 KB
  • examples/example-2-untyped-code/scenario.md 1 KB
  • examples/example-3-complex-generics/expected.md 3 KB
  • examples/example-3-complex-generics/input.py 1 KB
  • examples/example-3-complex-generics/scenario.md 1 KB

Versions

The database has no other skills named Python Code Review with Modern Typing.

Database snapshot: 13.11.2026 · package version 26652b2761f0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100python
    Python language conventions, modern idioms, and toolchain. Invoke whenever task involves any interaction with Python code — writing, reviewing, refactoring, debugging, or understanding Python projects.
  • 95python-style
    Applies Python coding conventions when writing, reviewing, or refactoring code. Covers .py files, docstrings, type annotations, naming, formatting, error handling, imports, file ordering, and ataraxis library preferences. Use when writing new Python code, modifying existing…
  • 95python-type-safety
    Modern Python type safety with type hints, generics, protocols, and strict type checking using ty and ruff. Use when adding type annotations, implementing generic classes, defining structural interfaces, configuring ty/ruff, or writing type-safe Python 3.13+/3.14+ code. Triggers…
  • 90python-code-review
    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.
  • 100python-patterns
    Picks a Python framework, async model and project structure, with typing and testing guidance. Use when starting or structuring a Python project.
  • 100python-idioms
    Modern Python (3.11+) idioms: type annotations, typing Protocols, Pydantic models, asyncio, pytest fixtures, and Ruff/Mypy strict compliance. Use when writing, refactoring, or reviewing Python applications, APIs, or scripts.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.