Optional, Union & the | Operator

Unions express values that may take multiple types. The X | Y syntax (3.10+) replaces Union[X, Y]; nullable types are unions with None.

Recipe

def parse_count(raw: str | None) -> int:
    if raw is None:
        return 0
    return int(raw)
 
def format_id(value: int | str) -> str:
    return str(value)

When to reach for this:

• Parsing optional config and env vars
• Functions returning "value or missing"
• Accepting multiple input representations
• Modeling success/failure without exceptions

Working Example

from dataclasses import dataclass
 
@dataclass
class User:
    id: int
    email: str | None
 
def email_domain(user: User) -> str | None:
    if user.email is None:
        return None
    return user.email.split("@", 1)[1]
 
def describe(value: int | str | None) -> str:
    match value:
        case None:
            return "missing"
        case int(n):
            return f"number {n}"
        case str(s):
            return f"text {s}"
 
def coalesce(*values: str | None) -> str:
    for v in values:
        if v is not None:
            return v
    return ""
 
if __name__ == "__main__":
    print(describe(42))
    print(email_domain(User(1, None)))

What this demonstrates:

• is None / is not None narrows optional types for checkers
• match/case with typed patterns refines unions
• str | None in variadic args for fallback chains
• Returning None explicit in return type

Deep Dive

How It Works

• Union - Value may be any member type; checker requires handling all cases.
• Narrowing - Control flow refinements shrink union to specific member.
• Optional alias - Optional[T] means T | None - still valid, | preferred style.
• Exhaustiveness - mypy --strict warns on unhandled union members in match.
• TypeGuard - Functions that narrow types for callers (advanced).

Narrowing Tools

Python Notes

from typing import TypeGuard
 
def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

Gotchas

• Truthy check vs None - if email: treats empty string as missing differently from is None. Fix: Pick explicit None vs falsy semantics.
• Optional overuse - Everything T | None obscures required fields. Fix: Required vs optional model fields separated.
• Union order - Generally irrelevant; checkers treat symmetrically.
• Returning Any from union branch - Widens result. Fix: Consistent return type per branch.
• JSON null - Maps to Python None - validate at boundary with Pydantic.

Alternatives

FAQs

Related

• Type Hints Basics - fundamentals
• Literal, Final & Annotated - precise unions
• TypedDict & NamedTuple - optional keys
• Control Flow - match narrowing

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.