PEP 0604 copyediting (#1189)

pep-0604.rst

@@ -10,22 +10,20 @@ Created: 28-Aug-2019
 Python-Version: 3.9
 
 
-Introduction
-============
+Abstract
+========
 
-This PEP describes an extension to Python language, which aims to add a complementary
-syntax to write ``Union[X,Y]`` easier.
+This PEP proposes a complementary syntax for ``Union[X,Y]`` and extends its
+purpose to ``isinstance`` and ``issubclass``.
 
 
 Motivation
 ==========
 
-The PEP484 [1]_ and PEP526 [2]_ propose a generic syntax to add typing to variables,
-parameters and function returns.
-The PEP585 [3]_ proposes to `expose parameters to generics at runtime <https://www.python.org/dev/peps/pep-0585/#id7>`_.
-MyPy [4]_ accepts a syntax which looks like something like this:
-
-::
+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 <https://www.python.org/dev/peps/pep-0585/#id7>`_.
+MyPy [4]_ accepts a syntax which looks like something like this::
 
     annotation: name_type
     name_type: NAME (args)?
@@ -39,15 +37,13 @@ The verbosity of this syntax does not help the adoption.
 Proposal
 ========
 
-Inspired by Scala language [5]_, this proposal adds operator ``__or__()`` in the root ``type``.
-With this new operator, it is possible to write ``int | str`` in place of ``Union[int,str]``.
-This proposition uses the standard meaning of the ``|`` operator.
-Then, it is possible to extend ``isinstance()`` and ``issubclass()``
-to accept this new syntax:
+Inspired by Scala language [5]_, this proposal adds operator ``type.__or__()``.
+With this new operator, it is possible to write ``int | str`` in place of
+``Union[int,str]``. The result of this expression would then be valid in
+``isinstance()`` and ``issubclass()``::
 
-::
-
-  isinstance(int, int | str)
+    isinstance(5, int | str)
+    issubclass(bool, int | float)
 
 Examples
 ========
@@ -61,22 +57,23 @@ Here are some examples of what we can do with this feature.
     def f(list: List[int | str], param: int | None) -> float | str:
         pass
 
-    f([1,"abc"],None)
+    f([1, "abc"], None)
 
     assert str | int == Union[str,int]
     assert str | int | float == Union[str, int, float]
 
     assert isinstance("", int | str)
-    assert issubclass(int, int | str)
+    assert issubclass(bool, int | float)
 
-Once the Python language is extended, MyPy [3]_ must be updated to accept this new syntax.
+Once the Python language is extended, MyPy [4]_ and other type checkers will
+need to be updated to accept this new syntax.
 
 Incompatible changes
 ====================
+
 In some situations, some exceptions will not be raised as expected.
 
-If some metaclass overload the ``__or__`` operator, the user must resolve the ambiguities with ``Union``.
-::
+If a metaclass implements the ``__or__`` operator, it will override this::
 
     >>> class M(type):
     ... 	def __or__(self,other): return "Hello"
@@ -90,14 +87,14 @@ If some metaclass overload the ``__or__`` operator, the user must resolve the am
     >>> Union[C,int]
     typing.Union[__main__.C, int]
 
-Dissenting Opinion
-==================
+Objections and responses
+========================
 
 - `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]``?
---------------------------------------------------
+-------------------------------------------------
 
 - CONS: This is not a new proposal. If I recall correctly, it was proposed way back at the very beginning of the
   type-hinting discussion, and there has been at least one closed feature request for it:
@@ -149,12 +146,12 @@ Dissenting Opinion
 
   - *A proposed patch of mypy is just 20 lines of codes*
 
-- If yes,
+- If yes, [??? incomplete?]
 
-Change only the PEP484 (Type hints) to accept the syntax ``type1 | type2`` ?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Change only the PEP 484 (Type hints) to accept the syntax ``type1 | type2`` ?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- PRO: The PEP563 [6]_ (Postponed Evaluation of Annotations) is enough to accept this proposition
+- PRO: PEP 563 (Postponed Evaluation of Annotations) is enough to accept this proposition
 - CONS: The Resolving type hints at runtime says: “For code which uses annotations for other purposes, a
   regular ``eval(ann, globals, locals)`` call is enough to resolve the annotation.". Without add a new
   operator ``__or__`` in type ``type``, it's not possible to resolve type hints at runtime.
@@ -212,18 +209,10 @@ A proposed implementation for `mypy is here
 References
 ==========
 
-.. [1] PEP484,
-   https://www.python.org/dev/peps/pep-0484/
-.. [2] PEP526,
-   https://www.python.org/dev/peps/pep-0526/
-.. [3] PEP585,
-   https://www.python.org/dev/peps/pep-0585/
 .. [4] MyPy
    http://mypy-lang.org/
 .. [5] Scala Union Types
    https://dotty.epfl.ch/docs/reference/new-types/union-types.html
-.. [6] PEP563,
-   https://www.python.org/dev/peps/pep-0563/
 
 Copyright
 =========