python-typing-patterns_skill

Overview

This skill teaches modern Python type hints and practical patterns for type safety and clearer code. It focuses on annotations, collections, generics, Protocols, TypedDict, type guards, and running mypy/pyright checks. The goal is predictable, self-documented APIs and safer refactors.

How this skill works

The skill inspects code patterns related to type hints (TypeVar, Generic, Protocol, TypedDict, overload, Literal, Final) and suggests idiomatic replacements and refinements. It explains how to use collection ABCs, structural typing, TypeGuards, and bounded TypeVars, and shows commands to run static checkers like mypy and pyright. It also points to common configuration and runtime-validation approaches.

When to use it

• When adding or improving type annotations in a codebase
• Before releasing a library to ensure stable public APIs
• While writing generic utilities or reusable components
• When onboarding teams to a consistent typing style
• To catch type regressions with CI type checks

Best practices

• Prefer collection ABCs (Sequence, Mapping) over concrete types for flexibility
• Use modern union syntax (X | None) on Python 3.10+ and avoid Optional alias confusion
• Use TypedDict for structured dict shapes and Required/NotRequired for precise keys
• Prefer Protocols for structural typing instead of inheritance when possible
• Leverage TypeGuard functions to narrow runtime types for safer code paths
• Run static checkers (mypy/pyright) in CI with strict settings

Example use cases

• Annotate public functions and internal helpers to document expectations and catch bugs
• Define a Protocol for plugins that only require a small callable surface
• Create a generic first() helper using TypeVar to preserve element types
• Use TypedDict for JSON-like API responses with required and optional fields
• Write a TypeGuard to validate dynamic input like web payloads before processing