Flexible function parameters
A function accepts text or numeric input.
Python · Type Alias
Union
A union type annotation allows a value to match one of several types. Modern Python uses X | Y; this is equivalent to Union[X, Y], whose shorthand is recommended.
- Since
- 3.10 for the X | Y syntax
How it works
A union type describes a value that may conform to any one of several types. Modern Python expresses this with the | operator; typing.Union[X, Y] remains equivalent, but the shorthand is recommended.
Syntax
Union[X, Y]
X | YParameters
| Name | Type | Description |
|---|---|---|
X, Y, ... | types | Types that may be accepted by the annotation; there must be at least one type argument. |
Returns
A union type describing values that match at least one of its member types.
Key points
Union[X, Y]describes a value that may be eitherXorY; the modern equivalent isX | Y.- Use the bracketed
Unionform or, preferably, the concise|syntax. - For new code, prefer
int | stroverUnion[int, str]. - Nested unions are normally flattened into one union containing all member types.
- Duplicate member types do not remain as separate entries in the resulting union.
- Union equality does not depend on the order in which member types are written.
Common mistakes
- A union requires at least one argument, and every argument must be a type.
Unionis for type annotations; it is not a class to subclass or construct.- Do not try to subscript an already parameterized union.
Example: Annotating a value with two possible types
def parse(value: int | str) -> int | str:
return value
print(parse(42))
print(parse("answer"))The parameter and return annotation each allow either an integer or a string.
When to use it
Alternative result shapes
An API result may be one of several model types.
Nullable annotations
A value is optional without using legacy Optional syntax.
Interview questions
QWhat does a Python union type represent, and how is it written?
A union annotation allows a value to have one of several specified types. For example, int | str is equivalent to Union[int, str], and the documentation recommends the | form.
Follow-up: What happens with nested unions? They are generally flattened, so Union[Union[int, str], float] is equivalent to Union[int, str, float], except when a type alias prevents evaluation of the underlying alias.
QHow does Python normalize union members?
Repeated members are removed, and argument order does not affect union equality. Thus Union[int, str, int] is equivalent to int | str, and reversing the members produces an equal union.
Follow-up: What does a one-member union become? Union[int] becomes int; the constructor returns the single type rather than a distinct union.
QWhen should modern code use X | Y instead of Union[X, Y]?
The | spelling became available for unions in Python 3.10. It is the modern spelling of typing.Union and works directly in annotations such as def f(x: int | str) -> str: ....
Follow-up: Can Union itself be instantiated or subclassed to customize this behavior? No; the documentation explicitly disallows both operations.
Related
typingtypes.UnionTypeTypeAliasType