python-peps/pep-0604.rst

263 lines
7.0 KiB
ReStructuredText

PEP: 604
Title: Allow writing union types as ``X | Y``
Author: Philippe PRADOS <python@prados.fr>, Maggie Moss <maggiebmoss@gmail.com>
Sponsor: Chris Angelico <rosuav@gmail.com>
BDFL-Delegate: Guido van Rossum <guido@python.org>
Discussions-To: typing-sig@python.org
Status: Accepted
Type: Standards Track
Topic: Typing
Content-Type: text/x-rst
Created: 28-Aug-2019
Python-Version: 3.10
Post-History: 28-Aug-2019, 05-Aug-2020
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 :pep:`expose
parameters to generics at runtime
<585#parameters-to-generics-are-available-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.
Simplified Syntax
-----------------
::
# 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]
The existing ``typing.Union`` and ``|`` syntax should be equivalent.
::
int | str == typing.Union[int, str]
typing.Union[int, int] == int
int | int == int
The order of the items in the Union should not matter for equality.
::
(int | str) == (str | int)
(int | str | float) == typing.Union[str, float, int]
Optional values should be equivalent to the new union syntax
::
None | t == typing.Optional[t]
A new Union.__repr__() method should be implemented.
::
str(int | list[str])
# int | list[str]
str(int | int)
# int
isinstance and issubclass
-------------------------
The new syntax should be accepted for calls to ``isinstance`` and ``issubclass`` as long as the Union items are valid arguments to ``isinstance`` and ``issubclass`` themselves.
::
# 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 <https://mail.python.org/archives/list/python-ideas@python.org/thread/FCTXGDT2NNKRJQ6CDEPWUXHVG2AAQZZY/>`_
- `Discussion in typing-sig <https://mail.python.org/archives/list/typing-sig@python.org/thread/D5HCB4NT4S3WSK33WI26WZSFEXCEMNHN/>`_
1. Add a new operator for ``Union[type1, type2]``?
--------------------------------------------------
PROS:
- This syntax can be more readable, and is similar to other languages (Scala, ...)
- At runtime, ``int|str`` might return a simple object in 3.10, rather than everything that
you'd need to grab from importing ``typing``
CONS:
- Adding this operator introduces a dependency between ``typing`` and ``builtins``
- Breaks the backport (in that ``typing`` can easily be backported but core ``types`` can't)
- If Python itself doesn't have to be changed, we'd still need to implement it in mypy, Pyre, PyCharm,
Pytype, and who knows what else (it's a minor change see "Reference Implementation")
2. Change only PEP 484 (Type hints) to accept the syntax ``type1 | type2`` ?
----------------------------------------------------------------------------
:pep:`563` (Postponed Evaluation of Annotations) is enough to accept this proposition,
if we accept to not be compatible with the dynamic evaluation of annotations (``eval()``).
::
>>> 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'
3. Extend ``isinstance()`` and ``issubclass()`` to accept ``Union`` ?
---------------------------------------------------------------------
::
isinstance(x, str | int) ==> "is x an instance of str or int"
PROS:
- If they were permitted, then instance checking could use an extremely clean-looking notation
CONS:
- Must migrate all of the ``typing`` module in ``builtin``
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
<https://github.com/python/cpython/pull/21515>`_.
- A proposed implementation for `mypy is here
<https://github.com/pprados/mypy/tree/PEP604>`_.
References
==========
.. [1] mypy
http://mypy-lang.org/
.. [2] Scala Union Types
https://dotty.epfl.ch/docs/reference/new-types/union-types.html
.. [3] Pike
http://pike.lysator.liu.se/docs/man/chapter_3.html#3.5
Copyright
=========
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End: