From e848cd7605a7891378ef1463e933939aa253df71 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Tue, 6 Sep 2016 21:12:44 -0700 Subject: [PATCH] Issue #27905: Docs for typing.Type[C], by Michael Lee. --- Doc/library/typing.rst | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index bc71e1e840..83a8dcf35a 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`. -- 2.40.0