maverick-python-typing

get2knowio's avatarfrom get2knowio

Python type hints, mypy, Protocol, and static typing best practices

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026
[Code Review]

When & Why to Use This Skill

This Claude skill provides expert guidance on Python static typing and type hints, helping developers implement modern syntax and best practices. It streamlines the adoption of mypy, Protocols, and Generics to enhance code maintainability, reduce runtime errors, and ensure type safety across complex Python projects through automated review standards.

Use Cases

  • Modernizing legacy codebases by migrating from older typing syntax (Union/Optional) to Python 3.10+ pipe operators for cleaner code.
  • Implementing structural typing using Protocols to decouple components and improve code flexibility while maintaining strict type safety.
  • Configuring mypy and static analysis tools in pyproject.toml to enforce strict typing standards and catch potential bugs before deployment.
  • Conducting automated code reviews to identify missing type hints in public APIs and suggesting improvements for better documentation and developer experience.
namemaverick-python-typing
descriptionPython type hints, mypy, Protocol, and static typing best practices
version1.0.0
- "dict["
- "# typeignore"

Python Typing Skill

Expert guidance for Python type hints and static type checking.

Modern Type Syntax

Future Annotations (Python 3.7+)

from __future__ import annotations

def process(items: list[str]) -> dict[str, int]:
    """Modern syntax without importing List, Dict."""
    return {item: len(item) for item in items}

Union Types (Python 3.10+)

# Modern
def func(value: str | None = None) -> int | float:
    pass

# Old style
from typing import Optional, Union
def func(value: Optional[str] = None) -> Union[int, float]:
    pass

Type Hints Best Practices

Function Signatures

def greet(name: str, age: int) -> str:
    return f"Hello {name}, age {age}"

Collections

from collections.abc import Sequence, Mapping

def process_items(items: Sequence[str]) -> Mapping[str, int]:
    """Accept any sequence, return any mapping."""
    return {item: len(item) for item in items}

Callable Types

from collections.abc import Callable

def apply(func: Callable[[int], str], value: int) -> str:
    return func(value)

Protocols (Structural Typing)

from typing import Protocol

class Drawable(Protocol):
    def draw(self) -> None: ...

def render(obj: Drawable) -> None:
    """Accepts any object with draw() method."""
    obj.draw()

Generics

from typing import TypeVar, Generic

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

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

    def pop(self) -> T:
        return self._items.pop()

Mypy Configuration

# pyproject.toml
[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

Review Severity

  • MAJOR: Missing type hints on public APIs, using Any without justification
  • MINOR: Missing return type hints, using old Union syntax
  • SUGGESTION: Could use Protocol for duck typing, could use TypedDict