Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

A Union is a type hint construct in Python used to indicate that a variable, parameter, or return value can accept one of several distinct types. It instructs static type checkers (such as mypy or pyright) that an expression is valid if its resolved type matches any of the types specified within the union declaration.

​
Syntax

Python supports two distinct syntaxes for defining a union, depending on the Python version. Python 3.9 and earlier (typing.Union): Requires importing Union from the typing module and passing the allowed types as arguments within square brackets. 
from typing import Union

VariableType = Union[int, str, float]
Python 3.10+ (PEP 604 Bitwise OR Operator): Introduces the | operator as syntactic sugar for union types, eliminating the need to import the typing module for this purpose. 
VariableType = int | str | float

​
Internal Mechanics and Evaluation Rules

At runtime, the typing module applies strict algebraic rules to Union objects. Static type checkers enforce these same rules during static analysis.
  1. Flattening: Nested unions are automatically flattened into a single, one-dimensional union.
  2. Deduplication: Duplicate types are silently discarded.
  3. Commutativity: The order of the types declared in the union is irrelevant; they are evaluated as a mathematical set.
  4. Single Type Reduction: A union containing only a single type evaluates directly to that underlying type.
from typing import Union


# 1. Flattening
assert Union[Union[int, str], float] == Union[int, str, float]


# 2. Deduplication
assert Union[int, int, str] == Union[int, str]


# 3. Commutativity
assert Union[int, str] == Union[str, int]


# 4. Single Type Reduction
assert Union[int] == int

​
Relationship with Optional

The typing.Optional construct is strictly an alias for a Union where one of the valid types is NoneType. The following three declarations are semantically and technically identical to a static type checker: 
from typing import Optional, Union

TypeA = Optional[int]
TypeB = Union[int, None]
TypeC = int | None  # Python 3.10+

​
Type Narrowing

When a variable is annotated with a Union, static type checkers restrict operations on that variable to the intersection of attributes common to all types in the union. To access type-specific methods or attributes, the developer must perform type narrowing (typically via isinstance() checks or match statements). This proves to the static analyzer that the variable has been constrained to a specific type within a given execution block. 
def process(value: int | str) -> None:
    # At this scope, 'value' is (int | str). 
    # Only operations valid for BOTH int and str are permitted.
    
    if isinstance(value, str):
        # Type narrowed to 'str'. String methods are now valid.
        value.upper()
    else:
        # Type narrowed to 'int' via exhaustive fallback.
        value.bit_length()
Master Python with Deep Grasping Methodology!Learn More