API design

Express that a function may return a normal value or an error object as part of its contract

When a function prefers to return error information instead of raising, when documenting APIs that return success flags or exception objects, when defining reusable result types for multiple functions

Python codebases that use static typing (typing module), libraries that expose functional‑style APIs, services that serialize results

Result = Union[first_type, second_type]

Result = Union[..., ...]

alias_name: identifier, first_type: type, second_type: type

• from typing import Union
• def function(...) -> Result
• isinstance(value
• Exception)

• Result = bool | Exception (PEP 604 pipe syntax)
• Result = Union[bool
• BaseException]

Forgetting to import Union (misconception: assuming Union is built-in) -> NameError when the type checker runs; using Union with unrelated types (misconception: Union can combine any types) -> type checker may miss incompatible return values; treating the returned Exception as a regular value without handling it (misconception: the Union returns a usable value) -> runtime errors when calling methods on the Exception assuming it is a bool; conflating runtime behavior with static type hints (misconception: Union changes runtime behavior) -> assuming the function will automatically raise or unwrap the error

Using typing.Any to ignore type specifics, using custom error classes instead of generic Exception, returning None and checking for falsy values

Coming from languages without static union types, developers may think the Union creates a runtime union type rather than a static hint; avoid assuming the return will be automatically unwrapped

• type alias
• Union
• type hint

Union only affects static analysis; at runtime it does nothing. Prefer raising exceptions for error handling unless a functional style is required. In Python 3.10+ prefer the pipe syntax for brevity

Makes function contracts explicit, helping static type checkers and readers understand possible error returns, reducing accidental misuse

Result can be success or failure – a boolean or an exception

Python 3.10 introduced PEP 604 allowing "bool | Exception" as a more concise alternative to Union

Result = bool | Exception # Python 3.10+ pipe syntax