Type Hints in Python: Annotate Your Code with Confidence

Type hints let you declare what type of data a variable, parameter, or return value should hold. Python itself doesn’t enforce them at runtime — but your IDE, static analysis tools like mypy, and data-validation libraries like Pydantic all use them heavily. Adding type hints is one of the highest-return habits you can build as a Python developer.

Why Type Hints Matter

Compare these two function signatures:

# Without type hints — what are name, age, and the return value?
def create_user(name, email, age):
    pass

# With type hints — instantly clear
def create_user(name: str, email: str, age: int) -> dict:
    pass

Type hints give you three concrete benefits:

Self-documenting code

Readers understand intent without reading the function body. Types serve as always-up-to-date documentation.

IDE superpowers

Your IDE provides accurate autocomplete, inline error detection, safe rename refactoring, and jump-to-definition — all driven by type information.

Tool integration

mypy catches type errors before you run your code. Pydantic reads your hints to validate and coerce data at runtime. FastAPI uses them to generate OpenAPI docs automatically.

Basic Variable Annotations

# Scalars
name:       str   = "Alice"
age:        int   = 30
price:      float = 19.99
is_active:  bool  = True

# Python does NOT enforce these at runtime
age: int = "not a number"   # runs without error — it's just a hint

Function Annotations

Annotate every parameter and the return type. The return type goes after ->.

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

def calculate_total(prices: list[float], tax_rate: float = 0.1) -> float:
    return sum(prices) * (1 + tax_rate)

def find_user(user_id: int) -> dict | None:
    # Returns a dict if found, None if not
    ...

# No meaningful return value — annotate with None
def log_event(message: str) -> None:
    print(f"[LOG] {message}")

Container Types

For collections, specify what they hold using square brackets (Python 3.9+):

# List
tags:       list[str]       = ["python", "fastapi"]
scores:     list[int]       = [95, 87, 72]

# Dictionary
headers:    dict[str, str]  = {"Content-Type": "application/json"}
word_freq:  dict[str, int]  = {"error": 12, "warning": 5}

# Tuple — specify type for each position
coords:     tuple[float, float]       = (51.5, -0.1)
rgb:        tuple[int, int, int]      = (255, 128, 0)

# Set
unique_ids: set[int]        = {1, 2, 3}

In Python 3.8 and earlier you had to import List, Dict, Tuple, Set from typing and use uppercase: List[int], Dict[str, int]. Since Python 3.9, lowercase built-in types work directly. Use lowercase for all new code.

Optional and Union Types

Use X | None (Python 3.10+) or Optional[X] (earlier versions) when a value might be absent:

from typing import Optional, Union

# These three are equivalent
middle_name: str | None = None          # preferred in Python 3.10+
middle_name: Optional[str] = None      # common in older code
middle_name: Union[str, None] = None   # explicit Union

# Practical example
def find_product(product_id: int) -> dict | None:
    products = {1: {"name": "Laptop"}, 2: {"name": "Mouse"}}
    return products.get(product_id)   # returns None if not found

result = find_product(99)
if result is None:
    print("Product not found")

Union Types (Multiple Allowed Types)

from typing import Union

# A value that can be int or float
def square(n: int | float) -> float:
    return float(n * n)

# A function that accepts str or bytes
def process(data: str | bytes) -> str:
    if isinstance(data, bytes):
        return data.decode("utf-8")
    return data

Literal Types — Restrict to Specific Values

Use Literal when only a fixed set of values is valid:

from typing import Literal

status:    Literal["pending", "approved", "rejected"]  = "pending"
log_level: Literal["debug", "info", "warning", "error"] = "info"
priority:  Literal["low", "medium", "high"]             = "medium"

def set_log_level(level: Literal["debug", "info", "warning", "error"]) -> None:
    print(f"Log level set to: {level}")

The `Any` Type

Any opts a variable out of type checking — it accepts any type and is compatible with every other type. Use it sparingly as an escape hatch:

from typing import Any

def log_value(value: Any) -> None:
    print(f"Value: {value}, Type: {type(value).__name__}")

log_value(42)
log_value("hello")
log_value([1, 2, 3])

Type Aliases

Give a long or frequently reused type a short name:

from typing import TypeAlias

UserId:    TypeAlias = int
UserDict:  TypeAlias = dict[str, str | int]
ProductList: TypeAlias = list[dict[str, str | float]]

def get_user(user_id: UserId) -> UserDict:
    return {"id": user_id, "name": "Alice", "age": 30}

Static Type Checking with mypy

mypy reads your type hints and catches mismatches before you run your code:

pip install mypy
mypy my_module.py

# my_module.py
def add(a: int, b: int) -> int:
    return a + b

result: str = add(1, 2)   # mypy reports: error: Incompatible types

Running mypy in your CI pipeline catches entire classes of bugs — passing the wrong argument type, returning the wrong shape from a function, calling a method that doesn’t exist on a type.

How Pydantic Builds on Type Hints

Pydantic takes type hints one step further: it enforces them at runtime, validates incoming data, and coerces values to the correct type where possible.

from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: float
    in_stock: bool = True

# Valid data — works perfectly
p = Product(name="Laptop", price=999)
print(p.price)        # 999.0  ← coerced from int to float
print(p.in_stock)     # True

# Invalid data — raises a detailed ValidationError
try:
    bad = Product(name="Mouse", price="not-a-number")
except Exception as e:
    print(e)
    # 1 validation error for Product
    # price — Input should be a valid number [...]

FastAPI uses Pydantic models as request bodies. The type hints you write on a BaseModel subclass define both the validation rules and the generated OpenAPI schema — your documentation, validation, and serialisation are all driven by the same type annotations.

Quick Reference

from typing import Optional, Literal, Any, Union

# Variable annotations
name:    str                           = "Alice"
count:   int                           = 0
amount:  float                         = 0.0
flag:    bool                          = False
tags:    list[str]                     = []
mapping: dict[str, int]                = {}
point:   tuple[float, float]           = (0.0, 0.0)

# Optional (may be None)
nickname: str | None                   = None

# Union (multiple types)
value:    int | float                  = 0

# Literal (one of a fixed set)
role:     Literal["admin", "user"]     = "user"

# Any (opt out of type checking)
data:     Any                          = None

# Function annotations
def process(items: list[str], limit: int = 10) -> list[str]:
    return items[:limit]

Core Python

Advanced Python

Pydantic

Type Hints in Python: Annotate Your Code with Confidence

Why Type Hints Matter

Self-documenting code

IDE superpowers

Tool integration

Basic Variable Annotations

Function Annotations

Container Types

Optional and Union Types

Union Types (Multiple Allowed Types)

Literal Types — Restrict to Specific Values

The `Any` Type

Type Aliases

Static Type Checking with mypy

How Pydantic Builds on Type Hints

Quick Reference

​Why Type Hints Matter

Self-documenting code

IDE superpowers

Tool integration

​Basic Variable Annotations

​Function Annotations

​Container Types

​Optional and Union Types

​Union Types (Multiple Allowed Types)

​Literal Types — Restrict to Specific Values

​The Any Type

​Type Aliases

​Static Type Checking with mypy

​How Pydantic Builds on Type Hints

​Quick Reference

Why Type Hints Matter

Basic Variable Annotations

Function Annotations

Container Types

Optional and Union Types

Union Types (Multiple Allowed Types)

Literal Types — Restrict to Specific Values

The `Any` Type

Type Aliases

Static Type Checking with mypy

How Pydantic Builds on Type Hints

Quick Reference