> ## 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.
# Python Union
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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:
```python theme={"dark"}
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.
```python theme={"dark"}
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()
```
Tired of Poor Python Skills? Fix That With Deep Grasping!
Learn More
