Type Hints & Annotations in Python

The Story That Explains Type Hints

Type hints are Python's way of writing down what kind of value each variable, argument, or return should be. They live in the code as annotations — Python itself ignores them at runtime — but tools like mypy, pyright, PyCharm, and VS Code use them to catch bugs, power autocompletion, and generate documentation.

The Problem — Untyped Python at Scale

Here's the same function twice. One is written the way most beginners write Python. The other has type hints. Both do exactly the same thing at runtime — but the second one catches bugs your teammates would ship.

# BEFORE — untyped
def greet(user):
    return "Hello " + user.name

# AFTER — typed
def greet(user: User) -> str:
    return f"Hello {user.name}"

The Three Places Type Hints Live

Anatomy of a Fully-Typed Function

def total(prices: list[float], tax: float = 0.0) -> float:
    return sum(prices) * (1 + tax)

# Callable with confidence:
result: float = total([9.99, 14.50, 3.20], tax=0.08)
print(result)   # 29.9052

Basic Types — Your Everyday Toolkit

# Variables
name: str          = "Ada"
age:  int          = 30
tags: list[str]    = ["dev", "python"]
scores: dict[str, float] = {"math": 91.5, "english": 88.0}
coord: tuple[float, float] = (51.5074, -0.1278)   # exactly 2 floats
unique_ids: set[int] = {101, 102, 103}

# Function
def describe(person: dict[str, str]) -> str:
    return f"{person['name']} ({person['role']})"

Optional Values — Handling None Safely

A value that might be either a real value or None is one of the most common patterns in Python. Type hints force you to declare and handle it — no more silent NoneType has no attribute 'x' crashes at 3 AM.

# Modern syntax (Python 3.10+) — preferred
def find_user(user_id: int) -> User | None:
    return db.get(user_id)   # returns User OR None

# Legacy syntax (still valid on 3.8+)
from typing import Optional
def find_user(user_id: int) -> Optional[User]:
    return db.get(user_id)

# Correct handling — mypy forces the None check
user = find_user(42)
if user is None:
    print("not found")
else:
    print(user.name)      # mypy KNOWS user is User here — autocomplete works!

Union Types — When a Value Could Be Several Things

Sometimes an argument could legitimately be one of several types. Use | (or Union[...] on older Python) to declare the possibilities.

# Modern (3.10+)
def to_int(value: int | str | float) -> int:
    return int(value)

# Narrowing with isinstance — mypy learns the type inside each branch
def describe_id(x: int | str) -> str:
    if isinstance(x, int):
        return f"numeric id: {x:06d}"       # mypy: x is int here
    return f"named id:   {x.upper()}"       # mypy: x is str here

Visual Diagram — The Type Checker Pipeline

Running mypy

# Install once
pip install mypy

# Check a single file
mypy my_script.py

# Check a whole project — strict mode catches everything
mypy --strict src/

# In CI: fail the build on any type error
mypy --strict src/ tests/ || exit 1

Callable, Iterable, Generator — Function & Sequence Types

from typing import Callable, Iterable, Iterator, Generator

# A parameter that is a function itself
def apply(fn: Callable[[int, int], int], a: int, b: int) -> int:
    return fn(a, b)
#      ^                ^                    ^
#   argument types    return type    fn takes (int, int) and returns int

apply(lambda x, y: x + y, 3, 4)    # 7

# Any iterable — accept lists, tuples, generators, sets, ...
def total(numbers: Iterable[float]) -> float:
    return sum(numbers)

# Generator that yields ints — Iterator[int] is usually enough
def count_up(n: int) -> Iterator[int]:
    for i in range(n):
        yield i

Structured Data — dataclass, TypedDict, NamedTuple

Real programs pass around structured data. Type hints shine here: your data shapes become first-class citizens the checker can verify.

from dataclasses import dataclass, field
from typing import TypedDict, NamedTuple

# 1) dataclass — the workhorse
@dataclass
class User:
    id: int
    name: str
    email: str
    active: bool = True
    tags: list[str] = field(default_factory=list)

u = User(id=1, name="Ada", email="ada@x.io")
print(u)   # User(id=1, name='Ada', email='ada@x.io', active=True, tags=[])

# 2) TypedDict — for JSON-shaped data you get from an API
class WeatherPayload(TypedDict):
    city: str
    temp_c: float
    humidity: int

def summarize(w: WeatherPayload) -> str:
    return f"{w['city']}: {w['temp_c']}°C"

summarize({"city": "London", "temp_c": 14.2, "humidity": 67})

# 3) NamedTuple — tiny, immutable, positional
class Point(NamedTuple):
    x: float
    y: float

p = Point(1.0, 2.0)
print(p.x, p.y)   # 1.0 2.0

Generics — Functions That Preserve Types

Sometimes a function is type-preserving: whatever type comes in, the same type comes out. A generic TypeVar tells mypy "this is the same type in and out."

from typing import TypeVar, Sequence

T = TypeVar("T")

def first(items: Sequence[T]) -> T | None:
    return items[0] if items else None

x = first([1, 2, 3])       # mypy: int | None
y = first(["a", "b", "c"]) # mypy: str | None  ← type flows through!

# Python 3.12+ has cleaner syntax with no TypeVar import:
def first[T](items: Sequence[T]) -> T | None:
    return items[0] if items else None

Protocols — Duck Typing, Verified

Python's philosophy is "if it walks like a duck and quacks like a duck, it's a duck." Protocol lets you type-check that structural style without demanding inheritance.

from typing import Protocol

class SupportsWrite(Protocol):
    def write(self, data: str) -> int: ...

def log(msg: str, sink: SupportsWrite) -> None:
    sink.write(msg + "\n")

# Any object with a matching .write() method is accepted
#   — no inheritance required, no registration required
import sys
log("starting", sys.stdout)             # works — stdout has .write

from io import StringIO
buf = StringIO()
log("buffered", buf)                    # also works — StringIO has .write

class Silent:
    def write(self, data: str) -> int:
        return len(data)          # our own class also matches

log("via silent", Silent())          # works

Common Pitfalls (and How to Avoid Them)

# WRONG — mutable default
def add_tag(item: str, tags: list[str] = []) -> list[str]:
    tags.append(item)
    return tags        # the SAME list persists across every call!

# RIGHT — sentinel None
def add_tag(item: str, tags: list[str] | None = None) -> list[str]:
    tags = list(tags) if tags is not None else []
    tags.append(item)
    return tags

Real-World Example — Typed Weather API Client

Here's a small but production-shaped program: fetch weather from an API, parse it into a typed model, and return a summary. Every step is annotated, and mypy would catch every common mistake.

from __future__ import annotations
from dataclasses import dataclass
from typing import TypedDict, Iterable
import requests

# ── 1) Raw shape of the API response ───────────────────
class CurrentWeather(TypedDict):
    temperature: float
    windspeed: float
    weathercode: int

class WeatherResponse(TypedDict):
    current_weather: CurrentWeather
    timezone: str

# ── 2) Domain model — clean, immutable, typed ───────────
@dataclass(frozen=True)
class CityWeather:
    city: str
    temp_c: float
    wind_kmh: float
    timezone: str

# ── 3) Fetch → parse → return typed object ──────────────
def fetch_weather(city: str, lat: float, lon: float) -> CityWeather | None:
    params = {"latitude": lat, "longitude": lon, "current_weather": True}
    r = requests.get("https://api.open-meteo.com/v1/forecast",
                     params=params, timeout=5)
    if r.status_code != 200:
        return None
    data: WeatherResponse = r.json()
    cw = data["current_weather"]
    return CityWeather(
        city=city,
        temp_c=cw["temperature"],
        wind_kmh=cw["windspeed"],
        timezone=data["timezone"],
    )

# ── 4) Consume — mypy checks every step ─────────────────
def format_report(entries: Iterable[CityWeather]) -> str:
    lines: list[str] = ["City         Temp     Wind"]
    for e in entries:
        lines.append(f"{e.city:12s} {e.temp_c:5.1f}°C  {e.wind_kmh:.1f} km/h")
    return "\n".join(lines)

CITIES: list[tuple[str, float, float]] = [
    ("Mumbai",   19.0760,  72.8777),
    ("New York", 40.7128, -74.0060),
    ("London",   51.5074, -0.1278),
]

results: list[CityWeather] = [
    w for c, lat, lon in CITIES
    if (w := fetch_weather(c, lat, lon)) is not None
]
print(format_report(results))

When to Use Type Hints — and When to Skip

Golden Rules