Most type hint guides teach you syntax. This one is about which annotations actually prevent bugs.

After two years of adding types to codebases that didn't have them — and watching which annotations caught real issues and which were just ceremony — I've settled on four patterns. They're not the four most commonly taught. They're the four that have caught production bugs before they shipped.

The gap between "mypy passes" and "your code is correct"

mypy can pass on code that will throw a TypeError at runtime. This happens often enough that it's worth understanding why.

The core issue: mypy checks the annotations you write, but it can't verify the annotations are accurate. If you annotate a function as accepting str when it sometimes receives None, mypy will accept the annotation and check callers against it — but the function will still fail at runtime when None shows up.

This matters because the value of type hints isn't in satisfying the type checker. It's in forcing yourself to be precise about what your code actually accepts and returns. The annotation is a claim. The bug comes from making a wrong claim.

The patterns below are the ones where getting the annotation right catches a class of bug at annotation time rather than runtime.

Pattern 1: Optional[X] vs Union[X, None] — and why you should use neither

Optional[str] is syntactic sugar for Union[str, None]. It's the most common type annotation that developers get wrong in a consistent direction: they use it too rarely when they mean "this can be None" and too often when they mean "this is usually a string but I'm not sure."

The bug pattern it catches:

# Without types
def get_user_name(user_id: int):
    user = db.get(user_id)
    return user.name  # AttributeError if user is None

# With the wrong annotation — mypy doesn't help you
def get_user_name(user_id: int) -> str:
    user = db.get(user_id)
    return user.name  # mypy is happy; still crashes at runtime

# With the right annotation — mypy catches the unguarded access
def get_user_name(user_id: int) -> Optional[str]:
    user = db.get(user_id)
    if user is None:
        return None
    return user.name  # safe

The rule: use Optional[X] only when you've verified that the value actually can be None and you're prepared to handle it at every call site. The annotation should reflect reality, not intent.

Modern Python (3.10+) allows str | None as equivalent syntax. Use whichever your codebase has standardized on.

What it catches: Unguarded None access. The annotation forces you to decide whether None is a valid state, and mypy will flag every call site that treats the return value as definitely non-None without a guard.

Pattern 2: TypeGuard for narrowing in conditionals

Type narrowing is how mypy (and your IDE) understand what type a variable has inside a conditional block. The built-in narrowing handles the common cases:

def process(value: str | int) -> str:
    if isinstance(value, str):
        return value.upper()  # mypy knows value is str here
    return str(value)         # mypy knows value is int here

But narrowing fails when the check is in a helper function:

def is_string(value: object) -> bool:
    return isinstance(value, str)

def process(value: str | int) -> str:
    if is_string(value):
        return value.upper()  # mypy error: int has no attribute upper
    return str(value)

mypy can't infer that is_string narrows the type. TypeGuard fixes this:

from typing import TypeGuard

def is_string(value: object) -> TypeGuard[str]:
    return isinstance(value, str)

def process(value: str | int) -> str:
    if is_string(value):
        return value.upper()  # mypy is now happy — and correct
    return str(value)

What it catches: Type errors that only appear when narrowing is delegated to a helper. This pattern comes up frequently in validation code — the kind of code that checks "is this a valid X?" before dispatching on it. Without TypeGuard, your validation code provides no type safety downstream.

Pattern 3: Protocol for duck typing that mypy understands

Python is built on duck typing — if it has the right methods, it works. Type annotations fight this by default, because isinstance checks against concrete classes.

Protocol bridges the gap:

from typing import Protocol

class Serializable(Protocol):
    def to_dict(self) -> dict: ...

def save(item: Serializable) -> None:
    data = item.to_dict()
    # persist data...

Now any class with a to_dict() -> dict method satisfies Serializable — no inheritance required. mypy checks structural compatibility at the call site.

The bug pattern this catches is subtle. Without Protocol, you have two options for typing heterogeneous inputs:

1. Use Any — no type safety
2. Create a common base class — requires touching all implementations, breaks if they're in third-party code

With Protocol, you can annotate exactly the interface you use. This matters most for:

• Library boundaries — you want to accept anything that looks like a file, a logger, or a cache, regardless of concrete type
• Test doubles — your mock objects can satisfy the protocol without inheriting from the real class
• Third-party classes — you can write a protocol that matches a third-party class without modifying it

class HasClose(Protocol):
    def close(self) -> None: ...

def cleanup(resource: HasClose) -> None:
    resource.close()

# Works with anything that has close(): file objects, database connections,
# custom resources, test doubles — no inheritance required

What it catches: Type errors at the boundary between components. If your component uses three methods of an object, Protocol lets you express exactly that dependency. If a caller passes something that doesn't have those three methods, mypy catches it.

Pattern 4: overload for functions with multiple valid signatures

Some functions behave differently depending on argument type. The usual workaround is Union return types, but that forces callers to handle cases that can't actually occur:

def parse(value: str | bytes) -> str | bytes:
    if isinstance(value, bytes):
        return value.decode()
    return value

result = parse("hello")
result.upper()  # mypy error: bytes has no attribute upper
# mypy doesn't know that str input → str output

@overload solves this:

from typing import overload

@overload
def parse(value: str) -> str: ...
@overload
def parse(value: bytes) -> str: ...

def parse(value: str | bytes) -> str:
    if isinstance(value, bytes):
        return value.decode()
    return value

result = parse("hello")
result.upper()  # correct — mypy knows this is str

The overloaded signatures are the type-checker declarations; the actual implementation is below them. mypy uses the overloads to determine the return type at each call site.

What it catches: Return type ambiguity in multi-dispatch functions. This is common in any function that accepts multiple input types and transforms them — parsers, converters, and coercions. Without overload, you either use Any (no safety) or accept false errors at call sites (noise that causes engineers to disable type checking).

When type hints don't help

Type hints are least valuable when:

• You're already handling all the cases (the annotation confirms what you already know)
• The function is trivially short (the annotation adds ceremony without reducing cognitive load)
• You're annotating purely for documentation rather than checking (mypy ignores annotations on unannotated call sites)

They're most valuable at boundaries — function signatures that cross module or component lines, public API surfaces, places where data changes shape. The interior of a private implementation function is often better left unannotated; the signature that other modules call should almost always be.

A practical approach: run mypy --strict on your public API surface and your test fixtures. Let the interior be more permissive. You'll catch the bugs that matter without spending time on annotations that don't.

The four patterns at a glance

Recommended reading

• mypy's Type narrowing docs — the authoritative reference on how narrowing works
• PEP 544 (Protocols) — the design rationale is readable and explains edge cases
• PEP 612 (Parameter Specification Variables) — if you're writing decorators, this is the next pattern to learn

If you're building automation scripts or CI pipelines in Python, the patterns above apply especially to the boundary between your orchestration code and the AWS/service libraries you're calling. The Python Automation Cookbook includes annotated versions of 25 production scripts where these patterns show up — it's the fastest way to see them in a working context rather than toy examples.

Tags: #python #typing #mypy #programming #bestpractices