diff -r 75d6d5d9b674 -r 8e08492979fb Doc/library/typing.rst --- a/Doc/library/typing.rst Tue Aug 30 10:47:49 2016 -0700 +++ b/Doc/library/typing.rst Tue Aug 30 14:33:23 2016 -0700 @@ -502,6 +502,43 @@ except KeyError: return default +.. class:: Type + + A variable of type ``Type[C]`` represents the class object of some object + of type `C`. For example:: + + a = 3 # Has type 'int' + b = type(a) # 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. + + It is also legal to use a union of classes as the parameter to ``Type``:: + + def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ... + + However, other special constructs such as ``Tuple`` or ``Callable`` are not + permitted as parameters. The only exception to this rule is the ``Any`` + type. ``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 :class:`collections.abc.Iterable`.