Type Hints in Python

March 12, 2026 · 5 min read · Updated March 13, 2026 · intermediate

python typing intermediate

Type hints let you annotate your Python code with information about the expected types of variables, function parameters, and return values. They turn Python from a dynamically-typed language into one that can communicate its intentions clearly to both humans and tools.

Why Use Type Hints?

If you have ever stared at a function like this and wondered what kind of object data actually is:

def process(data):
    # What is data? A dict? A list? Something else?
    return data.get('result')

Then you have felt the pain that type hints solve. When you add hints, the same function becomes self-documenting:

def process(data: dict) -> str:
    return data.get('result', '')

Tools like mypy, pyright, and IDEs like VS Code use these hints to catch bugs before you even run your code. You get autocomplete that actually works, refactoring that does not break things, and documentation that stays in sync with your code.

Getting Started with Basic Type Hints

Python 3.5 introduced type hints, and they have evolved significantly since then. Here is the basic syntax:

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

For function parameters and return types, use arrows:

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

def add(a: int, b: int) -> int:
    return a + b

Optional and Union Types

Sometimes a value can be something or nothing. In older Python, you might have used None and checked for it manually. Now you can be explicit:

from typing import Optional

def find_user(user_id: int) -> Optional[str]:
    # Returns a name or None if not found
    if user_id == 1:
        return "Alice"
    return None

The Optional[str] is shorthand for Union[str, None]. Both are valid, but Optional reads more naturally.

When a value could be one of several types, use Union:

from typing import Union

def parse_value(value: Union[int, float, str]) -> float:
    return float(value)

Generic Container Types

For lists, dictionaries, and other containers, specify what they contain:

from typing import List, Dict, Tuple, Set

names: List[str] = ["Alice", "Bob", "Charlie"]
scores: Dict[str, int] = {"Alice": 95, "Bob": 87}
coordinates: Tuple[int, int] = (10, 20)
unique_ids: Set[int] = {1, 2, 3}

You can nest these arbitrarily:

matrix: List[List[int]] = [[1, 2], [3, 4]]
user_data: Dict[str, List[Dict[str, str]]] = {
    "admins": [{"name": "Alice"}]
}

Python 3.9 introduced generics using built-in types directly, so you can write:

names: list[str] = ["Alice", "Bob"]
scores: dict[str, int] = {"Alice": 95}

Use the newer syntax if you target Python 3.9+, otherwise import from typing.

TypeVar for Reusable Types

When you want a function to work with any type but keep that type consistent within a single call, use TypeVar:

from typing import TypeVar

T = TypeVar('T')

def first(items: list[T]) -> T:
    return items[0]

name = first(["Alice", "Bob"])      # Inferred as str
number = first([1, 2, 3])           # Inferred as int

This is especially useful for generic data structures like stacks, queues, and caches. It allows you to write functions that work with any type while maintaining type safety throughout the operation.

Callable Types

Sometimes you need to accept a function as a parameter. Use Callable to specify the signature:

from typing import Callable

def apply_operation(func: Callable[[int, int], int], a: int, b: int) -> int:
    return func(a, b)

def add(x: int, y: int) -> int:
    return x + y

result = apply_operation(add, 5, 3)  # Returns 8

The syntax is Callable[[input_types], output_type]. This is particularly useful for callbacks, event handlers, and higher-order functions.

TypedDict for Structured Dictionaries

When you work with dictionaries that have a known structure, TypedDict makes intentions clear:

from typing import TypedDict

class User(TypedDict):
    name: str
    email: str
    age: int

def create_user(data: User) -> User:
    return data

user: User = {"name": "Alice", "email": "alice@example.com", "age": 30}

This differs from a regular dict because the keys and value types are enforced. IDEs can provide autocomplete for dictionary keys, and type checkers will catch typos in key names.

Practical Tips

Start gradually. You do not need to annotate everything at once. Start with public APIs and commonly-used functions. Adding type hints to every single variable in a large codebase can be overwhelming, so prioritize the interfaces that matter most.

Use # type: ignore sparingly. Sometimes external libraries do not have type annotations, and ignoring the warning is the pragmatic choice. Just do not overuse it, or you will lose the benefits of type checking.

Run a type checker. Install mypy (pip install mypy) and run it on your code:

mypy your_module.py

It will catch real bugs, from typos to incorrect types being passed around. Many teams run mypy in their CI pipeline to catch type errors before they reach production.

IDE support matters. VS Code with the Python extension, PyCharm, and other editors can highlight type errors as you type. This is where type hints truly shine—you get instant feedback about potential bugs without even running your code.

Consider your Python version. The typing module has evolved significantly. Python 3.9 added native generics, and Python 3.10 introduced the match statement with structural pattern matching. If you can target newer Python versions, your type hints will be cleaner and more readable.

Common Gotchas

There are a few things that trip up newcomers. First, type hints are not enforced at runtime—Python ignores them by default. Second, mutable default arguments like def foo(items: list = []) should be def foo(items: list = None) followed by if items is None: items = []. Third, avoid using Any unless absolutely necessary, as it defeats the purpose of type checking.