python-mypy

Python Mypy Type Checking Skill

This skill automatically activates when writing Python code to ensure proper type annotations and compatibility with Mypy static type checking.

Core Principles

• Type Safety: Catch type errors before runtime
• Gradual Typing: Start with critical paths, expand coverage over time
• Strict Mode: Enable strict checks for new code
• CI Integration: Run Mypy in continuous integration

Type Annotation Patterns

Function Signatures

from typing import Optional
from collections.abc import Sequence

# Good: Complete type hints
def process_items(
    items: list[str],
    max_count: int | None = None,
    debug: bool = False,
) -> dict[str, int]:
    """Process items and return counts."""
    result: dict[str, int] = {}
    # Implementation
    return result

# Good: Generic types with TypeVar
from typing import TypeVar

T = TypeVar('T')

def first(items: Sequence[T]) -> T | None:
    """Get first item from sequence."""
    return items[0] if items else None

Class Type Hints

from typing import ClassVar
from dataclasses import dataclass

@dataclass
class User:
    """User model with type hints."""

    id: int
    name: str
    email: str | None = None
    active: bool = True

    # Class variable
    _registry: ClassVar[dict[int, 'User']] = {}

    def __post_init__(self) -> None:
        """Register user after initialization."""
        self._registry[self.id] = self

Protocol for Structural Typing

from typing import Protocol

class Drawable(Protocol):
    """Protocol for drawable objects."""

    def draw(self) -> str:
        """Draw the object."""
        ...

def render(obj: Drawable) -> None:
    """Render any drawable object."""
    print(obj.draw())

# Any class with draw() method satisfies this
class Circle:
    def draw(self) -> str:
        return "○"

render(Circle())  # OK with Mypy

TypedDict for Structured Dictionaries

from typing import TypedDict, NotRequired

class UserDict(TypedDict):
    """Structured user dictionary."""
    id: int
    name: str
    email: NotRequired[str]  # Optional key (Python 3.11+)

def create_user(data: UserDict) -> None:
    """Create user from typed dictionary."""
    user_id: int = data["id"]  # Type-safe access
    # Mypy knows 'email' might not exist