From: Guido van Rossum <guido@python.org>
Date: Wed, 7 Sep 2016 04:12:44 +0000 (-0700)
Subject: Issue #27905: Docs for typing.Type[C], by Michael Lee.
X-Git-Tag: v3.6.0b1~360^2
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e848cd7605a7891378ef1463e933939aa253df71;p=thirdparty%2FPython%2Fcpython.git

Issue #27905: Docs for typing.Type[C], by Michael Lee.
---

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index bc71e1e840b4..83a8dcf35ae3 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -502,6 +502,45 @@ The module defines the following classes, functions and decorators:
           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`.