Type-Hinting Skill
Adding and tightening type annotations - an Agent Skill for Python 3.14 static typing.
What This Skill Does
Reviews modules and adds types: function signatures, TypedDict, Protocol, TypeVar bounds, assert isinstance narrowing, fixes Any leakage, configures mypy or pyright in pyproject.toml, and enables CI gate on changed paths.
When to Invoke
- New package before first release
- PR introducing
Anyor untyped public API - Gradual typing milestone in brownfield service
- Preparing library for PyPI consumers
Inputs
| Input | Why |
|---|---|
| Checker | mypy vs pyright team standard |
| Strictness | strict per module vs whole repo |
| Public API surface | __all__ and exported names first |
| Third-party stubs | types-* packages needed |
| Django/FastAPI | plugin config differences |
Outputs
- Annotated public functions and class attributes
pyproject.toml[tool.mypy]or[tool.pyright]TYPE_CHECKINGimports for circular deps# type: ignoreaudit with ticket refs only when unavoidableuv run mypy src/packageclean on scope
Guardrails
- Public API fully typed before internal helpers.
- No untyped defs in new code -
def foo(x: int) -> str. - Prefer Protocol over ABC for structural typing.
- Do not silence with bare ignore - narrow with
type: ignore[arg-type]+ comment. - Run checker in CI on diff paths - expand scope over sprints.
- Match runtime validation - Pydantic models align with TypedDict where shared.
Recipe
uv sync --extra dev
uv run mypy src/myservice
uv run pyright src/myservice # if pyright is standard
uv run pytest -qWorking Example
from collections.abc import Sequence
from typing import Protocol
class SupportsClose(Protocol):
def close(self) -> None: ...
def shutdown_all(resources: Sequence[SupportsClose]) -> None:
for r in resources:
r.close()FAQs
mypy or pyright?
pyright faster in editors; mypy mature plugin ecosystem - pick one per repo.
Typed Django models?
Use django-stubs in mypy plugins - skill documents extra deps.
Related
- Type Hints Basics - fundamentals
- mypy and pyright Setup - config
- Gradual Typing Strategy - rollout
- Protocols and Structural Typing - patterns
Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.