Abstract

This PEP proposes overloading the | operator on types to allow writing Union[X, Y] as X | Y, and allows it to appear in isinstance and issubclass calls.

Motivation

PEP 484 and PEP 526 propose a generic syntax to add typing to variables, parameters and function returns. PEP 585 proposes to expose parameters to generics at runtime. Mypy [1] accepts a syntax which looks like:

annotation: name_type
name_type: NAME (args)?
args: '[' paramslist ']'
paramslist: annotation (',' annotation)* [',']

• To describe a disjunction (union type), the user must use Union[X, Y].

The verbosity of this syntax does not help with type adoption.

Proposal

Inspired by Scala [2] and Pike [3], this proposal adds operator type.__or__(). With this new operator, it is possible to write int | str instead of Union[int, str]. In addition to annotations, the result of this expression would then be valid in isinstance() and issubclass():

isinstance(5, int | str)
issubclass(bool, int | float)

We will also be able to write t | None or None | t instead of Optional[t]:

isinstance(None, int | None)
isinstance(42, None | int)

Specification

The new union syntax should be accepted for function, variable and parameter annotations.

# Instead of
# def f(list: List[Union[int, str]], param: Optional[int]) -> Union[float, str]
def f(list: List[int | str], param: int | None) -> float | str:
    pass

f([1, "abc"], None)

# Instead of typing.List[typing.Union[str, int]]
typing.List[str | int]
list[str | int]

# Instead of typing.Dict[str, typing.Union[int, float]]
typing.Dict[str, int | float]
dict[str, int | float]

int | str == typing.Union[int, str]

typing.Union[int, int] == int
int | int == int

(int | str) == (str | int)
(int | str | float) == typing.Union[str, float, int]

None | t == typing.Optional[t]

str(int | list[str])
# int | list[str]

str(int | int)
# int

# valid
isinstance("", int | str)

# invalid
isinstance(2, list[int]) # TypeError: isinstance() argument 2 cannot be a parameterized generic
isinstance(1, int | list[int])

# valid
issubclass(bool, int | float)

# invalid
issubclass(bool, bool | list[int])

Incompatible changes

In some situations, some exceptions will not be raised as expected.

If a metaclass implements the __or__ operator, it will override this:

>>> class M(type):
...     def __or__(self, other): return "Hello"
...
>>> class C(metaclass=M): pass
...
>>> C | int
'Hello'
>>> int | C
typing.Union[int, __main__.C]
>>> Union[C, int]
typing.Union[__main__.C, int]

Objections and responses

For more details about discussions, see links below:

• Discussion in python-ideas
• Discussion in typing-sig

>>> from __future__ import annotations
>>> def foo() -> int | str: pass
...
>>> eval(foo.__annotations__['return'])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1, in <module>
TypeError: unsupported operand type(s) for |: 'type' and 'type'

isinstance(x, str | int) ==> "is x an instance of str or int"

Reference Implementation

A new built-in Union type must be implemented to hold the return value of t1 | t2, and it must be supported by isinstance() and issubclass(). This type can be placed in the types module. Interoperability between types.Union and typing.Union must be provided.

Once the Python language is extended, mypy [1] and other type checkers will need to be updated to accept this new syntax.

• A proposed implementation for cpython is here.
• A proposed implementation for mypy is here.

References

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.