Python Type Hints: Annotate Variables and Functions

Learn how to use Python type hints for variables, functions, and collections, and how Pydantic and FastAPI use them for runtime validation.

Type hints are one of Python’s most practical features for writing clear, maintainable code. They tell you — and your tools — what type of data a variable, parameter, or function should carry. While Python’s runtime ignores them completely (they’re never enforced by the interpreter), they are actively read and used by your IDE, static analysis tools like mypy, and validation libraries like Pydantic — which is at the heart of FastAPI. Understanding type hints is a prerequisite for working effectively with Pydantic models and FastAPI routes.

Basic Variable Type Hints

You annotate a variable using a colon followed by the type:

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

The : str, : int, : float, and : bool parts are type hints — they document intent but do not enforce anything at runtime.

Python Doesn’t Enforce Type Hints

This is the most important thing to understand upfront:

age: int = "not a number"   # Python allows this — no error

Type hints are annotations, not constraints. The Python interpreter runs this code without complaint. They exist for three purposes:

1. Documentation — code becomes self-explanatory.
2. IDE support — autocomplete, inline error detection, and refactoring work better.
3. Validation tools — Pydantic, mypy, and others read and act on them.

# Without type hints — what are the expected types?
def create_user(name, email, age):
    pass

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

Basic Types

The four types you’ll annotate most often:

# str — text
name: str = "Alice"
message: str = "Hello, world!"

# int — whole numbers
count: int = 42
user_id: int = 1001

# float — decimal numbers
price: float = 29.99
temperature: float = 98.6

# bool — True or False
is_active: bool = True
has_access: bool = False

Container Types

For collections, you specify the type of their contents:

# List of strings
tags: list[str] = ["python", "pydantic", "fastapi"]

# List of integers
quantities: list[int] = [1, 5, 3, 2]

# Dictionary with string keys and integer values
word_counts: dict[str, int] = {"error": 12, "warning": 5}

# Dictionary with string keys and string values
settings: dict[str, str] = {"theme": "dark", "language": "en"}

# Nested: list of dictionaries
users: list[dict[str, str]] = [{"name": "Alice"}, {"name": "Bob"}]

Python 3.9+ supports lowercase built-in types (list, dict, set, tuple) directly in annotations. Older code imports uppercase equivalents from typing (List, Dict). They are equivalent — prefer the lowercase built-in syntax in new code.

Optional Values

When a value might be None, use Optional from typing or the | union syntax (Python 3.10+):

from typing import Optional

# These three are equivalent
middle_name: Optional[str] = None
middle_name: str | None = None

# Practical examples
phone: str | None = None
phone = "[phone]"   # valid assignment
phone = None            # also valid

Literal Types

When a variable must be one of a fixed set of values, use Literal:

from typing import Literal

status: Literal["draft", "published", "archived"] = "draft"

# Type checkers warn if you assign an unlisted value
log_level: Literal["debug", "info", "warning", "error"] = "info"
priority:  Literal["low", "medium", "high"]              = "medium"

Function Type Hints

Type hints on function parameters and return values are especially valuable:

def format_price(amount: float, currency: str = "USD") -> str:
    return f"{currency} {amount:.2f}"

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

def get_config(key: str) -> str | None:
    # Returns the value if found, None if the key doesn't exist
    pass

The -> str after the closing parenthesis declares the return type.

Common Patterns

from typing import Optional, Literal

# Required string (no default)
name: str

# Optional string — can be None
nickname: str | None = None

# String with a default value
country: str = "USA"

# List of items — starts empty
items: list[str] = []

# Dictionary — starts empty
metadata: dict[str, str] = {}

# Specific allowed values
role: Literal["admin", "user", "guest"] = "user"

Type Hints Don’t Validate — Pydantic Does

Remember: Python’s runtime ignores type hints entirely:

age: int = "not a number"           # No error
prices: list[float] = "not a list"  # No error

This is exactly where Pydantic comes in. Pydantic reads your type hints at class-definition time and generates real validators that run when objects are created:

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

u = User(name="Alice", age="25")   # "25" is coerced to int 25
print(u.age)         # 25
print(type(u.age))   # <class 'int'>

# Invalid data raises a clear ValidationError
u2 = User(name="Bob", age="not-a-number")
# pydantic_core.ValidationError: 1 validation error for User
# age: Input should be a valid integer [...]

FastAPI uses Pydantic models for all request and response bodies, so your type hints automatically become validation rules, serialisation schemas, and OpenAPI documentation — all at once.