Issue #27905: Docs for typing.Type[C], by Michael Lee. (Merge 3.5->3.6)

diff --cc Doc/library/typing.rst
index d902a153356f6c9601fdbff76a0358ea6902d385,83a8dcf35ae3a4a0673b391cda0e7e344dcbbce7..0139c75326b52015e7dbc223fa93cbecf1b04831
--- 1/Doc/library/typing.rst
--- 2/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@@ -502,9 -502,48 +502,48 @@@ The module defines the following classe
            except KeyError:
                return default
  
+ .. class:: Type
+ 
+    A variable annotated with ``C`` may accept a value of type ``C``. In
+    contrast, a variable annotated with ``Type[C]`` may accept values that are
+    classes themselves -- specifically, it will accept the *class object* of
+    ``C``. For example::
+ 
+       a = 3         # Has type 'int'
+       b = int       # Has type 'Type[int]'
+       c = type(a)   # Also has type 'Type[int]'
+ 
+    Note that ``Type[C]`` is covariant::
+ 
+       class User: ...
+       class BasicUser(User): ...
+       class ProUser(User): ...
+       class TeamUser(User): ...
+ 
+       # Accepts User, BasicUser, ProUser, TeamUser, ...
+       def make_new_user(user_class: Type[User]) -> User:
+           # ...
+           return user_class()
+ 
+    The fact that ``Type[C]`` is covariant implies that all subclasses of
+    ``C`` should implement the same constructor signature and class method
+    signatures as ``C``. The type checker should flag violations of this,
+    but should also allow constructor calls in subclasses that match the
+    constructor calls in the indicated base class. How the type checker is
+    required to handle this particular case may change in future revisions of
+    PEP 484.
+ 
+    The only legal parameters for ``Type`` are classes, unions of classes, and
+    ``Any``. For example::
+ 
+       def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...
+ 
+    ``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent
+    to ``type``, which is the root of Python's metaclass hierarchy.
+ 
  .. class:: Iterable(Generic[T_co])
  
 -    A generic version of the :class:`collections.abc.Iterable`.
 +    A generic version of :class:`collections.abc.Iterable`.
  
  .. class:: Iterator(Iterable[T_co])