Updates for PEPs 484 and 483 (#111)

Author: ilevkivskyi

pep-0483.txt

@@ -184,14 +184,16 @@ defined by three rules:
    subtype of ``t2``. (But not the other way around.)
 -  ``Any`` is consistent with every type. (But ``Any`` is not a subtype
    of every type.)
--  Every type is a subtype of ``Any``. (Which also makes every type
-   consistent with ``Any``, via rule 1.)
+-  Every type is consistent with ``Any``. (But every type is not a subtype
+   of ``Any``.)
 
 That's all! See Jeremy Siek's blog post `What is Gradual
 Typing <http://wphomes.soic.indiana.edu/jsiek/what-is-gradual-typing/>`_
-for a longer explanation and motivation. Note that rule 3 places ``Any``
-at the root of the type graph. This makes it very similar to
-``object``. The difference is that ``object`` is not consistent with
+for a longer explanation and motivation. ``Any`` can be considered a type
+that has all values and all methods. Combined with the definition of
+subtyping above, this places ``Any`` partially at the top (it has all values)
+and bottom (it has all methods) of the type hierarchy. Contrast this to
+``object`` -- it is not consistent with
 most types (e.g. you can't use an ``object()`` instance where an
 ``int`` is expected). IOW both ``Any`` and ``object`` mean
 "any type is allowed" when used to annotate an argument, but only ``Any``
@@ -269,14 +271,14 @@ between classes and types the following general rules apply:
 -  No types defined below can be subclassed, except for ``Generic`` and
    classes derived from it.
 -  All of these will raise ``TypeError`` if they appear
-   in ``isinstance`` or ``issubclass``.
+   in ``isinstance`` or ``issubclass`` (except for unparametrized generics).
 
 
 Fundamental building blocks
 ---------------------------
 
--  **Any**. Every type is a subtype of ``Any``; however, to the static
-   type checker it is also consistent with every type (see above).
+-  **Any**. Every type is consistent with ``Any``; and
+   it is also consistent with every type (see above).
 -  **Union[t1, t2, ...]**. Types that are subtype of at least one of
    ``t1`` etc. are subtypes of this.
 
@@ -292,9 +294,7 @@ Fundamental building blocks
       Example: ``Union[Employee, Manager] == Union[Employee]``.
    *  ``Union[t1]`` returns just ``t1``. ``Union[]`` is illegal,
       so is ``Union[()]``
-   *  Corollary: ``Union[..., Any, ...]`` returns ``Any``;
-      ``Union[..., object, ...]`` returns ``object``; to cut a
-      tie, ``Union[Any, object] == Union[object, Any] == Any``.
+   *  Corollary: ``Union[..., object, ...]`` returns ``object``.
 
 -  **Optional[t1]**. Alias for ``Union[t1, None]``, i.e. ``Union[t1,
    type(None)]``.

pep-0484.txt

@@ -1008,9 +1008,9 @@ one value::
 The ``Any`` type
 ----------------
 
-A special kind of type is ``Any``.  Every type is a subtype of
-``Any``.  This is also true for the builtin type ``object``.
-However, to the static type checker these are completely different.
+A special kind of type is ``Any``.  Every type is consistent with
+``Any``.  It can be considered a type that has all values and all methods.
+Note that ``Any`` and builtin type ``object`` are completely different.
 
 When the type of a value is ``object``, the type checker will reject
 almost all operations on it, and assigning it to a variable (or using
@@ -1705,8 +1705,8 @@ convenience definitions.
 Note that special type constructs, such as ``Any``, ``Union``,
 and type variables defined using ``TypeVar`` are only supported
 in the type annotation context, and ``Generic`` may only be used
-as a base class. All of these will raise ``TypeError`` if appear
-in ``isinstance`` or ``issubclass``.
+as a base class. All of these (except for unparameterized generics)
+will raise ``TypeError`` if appear in ``isinstance`` or ``issubclass``.
 
 Fundamental building blocks: