Python type hints explained: what developers should know

Why type hints matter in Python

Python type hints explained: what developers should know starts with a simple fact: untyped code becomes harder to understand and maintain as projects grow. When you're reviewing a pull request from a colleague, or jumping back into your own code six months later, type annotations act as inline documentation that editors and linters can actually verify. This isn't about enforcing types at runtime—Python remains dynamically typed—but about giving your team and your tools the information they need to catch bugs early and make refactoring safer.

Over the past few years, Python's type system has matured significantly. The ecosystem now treats type hints as a first-class feature, with tools like mypy and Pyright providing strict checking that rivals compiled languages. If you're building backend services that other developers depend on—APIs, shared libraries, microservices—clear type annotations can prevent entire categories of bugs from reaching production.

Annotate function parameters and returns

The foundation of effective typing is marking what goes in and what comes out. Every function parameter should declare its expected type, and every function should declare its return type. This makes your intent explicit and gives type checkers something concrete to verify.

Consider a real scenario: calculating the total cost of items in an order with optional tax. Here's the typed version:

def total(items: list[Item], tax: float = 0.0) -> float:
    return sum(i.price for i in items) * (1 + tax)

The annotations tell us that items must be a list of Item objects, tax is a float with a default of zero, and the function returns a float. Anyone calling this function immediately understands what to pass in. A type checker will flag it if someone accidentally passes a string for tax, or tries to use the result in a context where a string is expected.

Without annotations, you'd have to infer this from a docstring or trial and error. And docstrings can become outdated; type annotations are checked on every run of your linter.

Let's look at a more complex example with user authentication:

def authenticate_user(username: str, password: str) -> User | None:
    """Return authenticated user or None if credentials fail."""
    user = db.query(User).filter(User.username == username).first()
    if user and user.verify_password(password):
        return user
    return None

The return type User | None signals immediately that callers must handle the possibility of no user being returned. This is far clearer than a docstring and, critically, type checkers will complain if you forget to handle the None case downstream.

Use list[int] and dict[str, User] generics (Python 3.9+)

Before Python 3.9, you had to import from the typing module to use generic types. You'd write from typing import List, Dict and then List[int] instead of list[int]. This was awkward and inconsistent with how Python actually works.

Python 3.9 unified the syntax: built-in types like list, dict, set, and tuple became generic directly. Now you write what you mean:

def process_order(
    items: list[dict[str, int]],
    taxes_by_region: dict[str, float],
    tags: set[str]
) -> tuple[float, list[str]]:
    """
    Process items and return total cost and applied discounts.
    
    items: list of {product_id: quantity} dicts
    """
    total_cost = 0.0
    discounts_applied = []
    
    for item in items:
        for product_id, quantity in item.items():
            price = get_product_price(product_id)
            total_cost += price * quantity
    
    for region in tags:
        if region in taxes_by_region:
            total_cost *= (1 + taxes_by_region[region])
            discounts_applied.append(f"Applied {region} tax")
    
    return total_cost, discounts_applied

The signature now reads naturally. We're accepting a list of dictionaries, a dictionary mapping regions to tax rates, a set of tags, and we return a tuple with a cost and a list of discount descriptions. Type checkers understand this completely, and so does anyone reading your code.

For more complex generic types, you'll still need the typing module—things like Callable, Union, and custom generics. But for container types, stick with the built-in syntax when your project targets Python 3.9 or later.

Use X | None instead of Optional[X] (Python 3.10+)

Handling None values is central to robust Python code. Traditionally, you'd import Optional from typing and write Optional[User] to indicate "a User or None". It works, but it's verbose and unintuitive compared to what you might write in TypeScript or Rust.

Python 3.10 introduced the union operator |, so now you write User | None, which reads much more naturally. It's also shorter and aligns with how developers think: "I get back either a User or nothing."

Here's a practical example from a CRM backend:

def find_contact(contact_id: int) -> Contact | None:
    return db.query(Contact).get(contact_id)

def get_contact_safe(contact_id: int) -> Contact:
    """Raises NotFoundError if contact missing."""
    contact = find_contact(contact_id)
    if contact is None:
        raise NotFoundError(f"Contact {contact_id} not found")
    return contact

def merge_contacts(primary_id: int, secondary_id: int | None) -> Contact | None:
    """Merge secondary into primary. Returns merged contact or None if primary missing."""
    primary = find_contact(primary_id)
    if primary is None:
        return None
    if secondary_id is None:
        return primary
    secondary = find_contact(secondary_id)
    # merge logic...
    return primary

Notice how the types immediately signal what can be None and what cannot. get_contact_safe guarantees a Contact in its return, so callers never need to check for None. find_contact returns Contact | None, so type checkers will warn if you forget to handle the None case. And merge_contacts accepts an optional secondary_id and can itself return None, reflecting the actual business logic.

If you're stuck on Python 3.9, use Optional[X] from the typing module. But if you can upgrade to 3.10 or later, X | None is the modern, cleaner choice.

Run mypy or pyright in CI

Type annotations only matter if you actually check them. A type checker examines your code, compares how you use values against how you've annotated them, and reports mismatches. The two mainstream choices are mypy (the original and most widely used) and Pyright (Microsoft's stricter alternative, popular in the Python/TypeScript community).

Both should run as part of your CI pipeline, failing the build if type errors are found. This prevents untyped or incorrectly typed code from merging.

A typical setup might look like this:

# pyproject.toml
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

[tool.pyright]
pythonVersion = "3.11"
typeCheckingMode = "strict"

And in your CI (GitHub Actions, GitLab CI, etc.):

- name: Type check with mypy
  run: mypy src/

With disallow_untyped_defs = true, mypy requires that every function be typed. This might feel strict at first, but it forces consistency and catches bugs early. You can always mark deliberately untyped code with # type: ignore comments for specific lines, but this should be the exception, not the rule.

In e-commerce and ride-hailing systems we've worked on, turning on strict type checking caught approximately one bug per 500 lines of code that would have slipped into production. That's significant.

Common mistakes

• Forgetting the return type: Functions without explicit return types are a red flag. Even if it's just -> None, be explicit.
• Using Any everywhere: Any is a type, but it's the escape hatch. If you find yourself writing list[Any] frequently, reconsider your design. What actually goes in that list?
• Mutable default arguments and types: def foo(items: list[Item] = []) is both a type error (mutable defaults) and a runtime bug. Use items: list[Item] | None = None and initialize inside the function.
• Ignoring type checker warnings: If mypy complains about an assignment, that's a real problem. Suppress it only if you fully understand why and add a comment.
• Assuming types at runtime: Type hints are not enforced at runtime. If you need runtime validation—e.g., in an API endpoint—use a library like Pydantic or Marshmallow alongside type hints.

Key takeaways

• Annotate every function parameter and return type. This is the foundation of readable, maintainable code.
• Use list[int], dict[str, Value], and similar built-in generics on Python 3.9+. It's clearer than importing from typing.
• Prefer X | None to Optional[X] on Python 3.10+. It's more readable and modern.
• Run mypy or Pyright in CI with strict settings. Enforce that all functions are typed.
• Type hints are not runtime enforcement; they're a contract for your code and a tool for static analysis. Combine them with runtime validation where needed.
• Treat type checking as a cheap form of testing. The time investment pays for itself within weeks.