PEP 604 - Updates and Edits (#1550)

pep-0604.rst

@@ -3,11 +3,13 @@ Title: Allow writing union types as ``X | Y``
 Author: Philippe PRADOS <python@prados.fr>
 Sponsor: Chris Angelico <rosuav@gmail.com>
 BDFL-Delegate: Guido van Rossum <guido@python.org>
+Discussions-To: typing-sig@python.org
 Status: Draft
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 28-Aug-2019
 Python-Version: 3.10
+Post-History: 28-Aug-2019, 05-Aug-2020
 
 
 Abstract
@@ -34,7 +36,7 @@ Mypy [1]_ accepts a syntax which looks like::
 
 - To describe a disjunction (union type), the user must use ``Union[X, Y]``.
 
-The verbosity of this syntax does not help the adoption.
+The verbosity of this syntax does not help with type adoption.
 
 
 Proposal
@@ -55,12 +57,13 @@ We will also be able to write ``t | None`` or ``None | t`` instead of
     isinstance(None, int | None)
     isinstance(42, None | int)
 
+Specification
+=============
 
-Examples
-========
-
-Here are some examples of what we can do with this feature.
+The new union syntax should be accepted for function, variable and parameter annotations.
 
+Simplified Syntax
+-----------------
 ::
 
     # Instead of
@@ -70,24 +73,67 @@ Here are some examples of what we can do with this feature.
 
     f([1, "abc"], None)
 
-    assert str | int == Union[str,int]
-    assert str | int | float == Union[str, int, float]
+    # Instead of typing.List[typing.Union[str, int]]
+    typing.List[str | int]
+    list[str | int]
 
-    assert isinstance("", int | str)
-    assert issubclass(bool, int | float)
+    # Instead of typing.Dict[str, typing.Union[int, float]]
+    typing.Dict[str, int | float]
+    dict[str, int | float]
 
-Once the Python language is extended, mypy [1]_ and other type checkers will
-need to be updated to accept this new syntax.
+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]
 
 
-Implementation
-==============
+Optional values should be equivalentl 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])
 
-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.
 
 
 Incompatible changes
@@ -118,13 +164,13 @@ 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]``?
--------------------------------------------------
+1. Add a new operator for ``Union[type1, type2]``?
+--------------------------------------------------
 
 PROS:
 
-- This syntax can be more readable, and is similary to others languages (Scala, ...)
-- At runtime, ``int|str`` might return a simple object in 3.9, rather than everything that
+- 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``
 
 
@@ -133,7 +179,7 @@ CONS:
 - Adding this operator introduce a dependency between ``typing`` and ``builtins``
 - As breaking 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"
+  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`` ?
@@ -163,16 +209,25 @@ if we accept to not be compatible with the dynamic evaluation of annotations (``
 PROS:
 
 - If they were permitted, then instance checking could use an extremely clean-looking notation
-- The implementation can use the tuple present in ``Union`` parameter, without create a new instance
 
 CONS:
 
-- Must migrate all the ``typing`` module in ``builtin``
+- 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