Abstract

This PEP proposes a complementary syntax for Union[X,Y] and extends its purpose to isinstance and issubclass.

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, the user must use Union[X,Y].

The verbosity of this syntax does not help the adoption.

Proposal

Inspired by Scala language [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]. The result of this expression would then be valid in isinstance() and issubclass():

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

Examples

Here are some examples of what we can do with this feature.

# in place 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)

assert str | int == Union[str,int]
assert str | int | float == Union[str, int, float]

assert isinstance("", int | str)
assert issubclass(bool, int | float)

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

Technical point of view

To accept to extend isinstance() and issubclass(), the object _GenericAlias must be available as a core, that doesn't have a directly-accessible name but via alias in typing module..

Incompatible changes

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

For backward compatibility, typing.py must say _GenericAlias = _GenericAlias.

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 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.