[Python-checkins] cpython (3.5): Issue #26141: Update docs for typing.py. Ivan Levkivskyi. (Backport from the
guido.van.rossum
python-checkins at python.org
Sat Sep 10 22:05:53 EDT 2016
https://hg.python.org/cpython/rev/1dc45beca118
changeset: 103604:1dc45beca118
branch: 3.5
parent: 103601:75514816741a
user: Guido van Rossum <guido at python.org>
date: Sat Sep 10 19:03:22 2016 -0700
summary:
Issue #26141: Update docs for typing.py. Ivan Levkivskyi. (Backport from the 3.6 version)
files:
Doc/library/typing.rst | 127 +++++++++++++++++++++++++---
1 files changed, 113 insertions(+), 14 deletions(-)
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -62,10 +62,12 @@
Note that ``None`` as a type hint is a special case and is replaced by
``type(None)``.
+.. _distinct:
+
NewType
-------
-Use the ``NewType`` helper function to create distinct types::
+Use the :func:`NewType` helper function to create distinct types::
from typing import NewType
@@ -103,7 +105,7 @@
This also means that it is not possible to create a subtype of ``Derived``
since it is an identity function at runtime, not an actual type. Similarly, it
-is not possible to create another ``NewType`` based on a ``Derived`` type::
+is not possible to create another :func:`NewType` based on a ``Derived`` type::
from typing import NewType
@@ -206,7 +208,7 @@
return self.value
def log(self, message: str) -> None:
- self.logger.info('{}: {}'.format(self.name, message))
+ self.logger.info('%s: %s', self.name, message)
``Generic[T]`` as a base class defines that the class ``LoggedVar`` takes a
single type parameter ``T`` . This also makes ``T`` valid as a type within the
@@ -533,10 +535,10 @@
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.
+ :pep:`484`.
- The only legal parameters for ``Type`` are classes, unions of classes, and
- ``Any``. For example::
+ The only legal parameters for :class:`Type` are classes, unions of classes, and
+ :class:`Any`. For example::
def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ...
@@ -545,11 +547,15 @@
.. 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])
- A generic version of the :class:`collections.abc.Iterator`.
+ A generic version of :class:`collections.abc.Iterator`.
+
+.. class:: Reversible(Iterable[T_co])
+
+ A generic version of :class:`collections.abc.Reversible`.
.. class:: SupportsInt
@@ -569,15 +575,18 @@
An ABC with one abstract method ``__round__``
that is covariant in its return type.
-.. class:: Reversible
-
- An ABC with one abstract method ``__reversed__`` returning
- an ``Iterator[T_co]``.
-
.. class:: Container(Generic[T_co])
A generic version of :class:`collections.abc.Container`.
+.. class:: Hashable
+
+ An alias to :class:`collections.abc.Hashable`
+
+.. class:: Sized
+
+ An alias to :class:`collections.abc.Sized`
+
.. class:: AbstractSet(Sized, Iterable[T_co], Container[T_co])
A generic version of :class:`collections.abc.Set`.
@@ -649,6 +658,18 @@
A generic version of :class:`collections.abc.ValuesView`.
+.. class:: Awaitable(Generic[T_co])
+
+ A generic version of :class:`collections.abc.Awaitable`.
+
+.. class:: AsyncIterable(Generic[T_co])
+
+ A generic version of :class:`collections.abc.AsyncIterable`.
+
+.. class:: AsyncIterator(AsyncIterable[T_co])
+
+ A generic version of :class:`collections.abc.AsyncIterator`.
+
.. class:: Dict(dict, MutableMapping[KT, VT])
A generic version of :class:`dict`.
@@ -657,6 +678,10 @@
def get_position_in_index(word_list: Dict[str, int], word: str) -> int:
return word_list[word]
+.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
+
+ A generic version of :class:`collections.defaultdict`
+
.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
A generator can be annotated by the generic type
@@ -681,7 +706,7 @@
start += 1
Alternatively, annotate your generator as having a return type of
- ``Iterator[YieldType]``::
+ either ``Iterable[YieldType]`` or ``Iterator[YieldType]``::
def infinite_stream(start: int) -> Iterator[int]:
while True:
@@ -752,6 +777,15 @@
are in the _fields attribute, which is part of the namedtuple
API.)
+.. function:: NewType(typ)
+
+ A helper function to indicate a distinct types to a typechecker,
+ see :ref:`distinct`. At runtime it returns a function that returns
+ its argument. Usage::
+
+ UserId = NewType('UserId', int)
+ first_user = UserId(1)
+
.. function:: cast(typ, val)
Cast a value to a type.
@@ -769,6 +803,34 @@
forward references encoded as string literals, and if necessary
adds ``Optional[t]`` if a default value equal to None is set.
+.. decorator:: overload
+
+ The ``@overload`` decorator allows describing functions and methods
+ that support multiple different combinations of argument types. A series
+ of ``@overload``-decorated definitions must be followed by exactly one
+ non-``@overload``-decorated definition (for the same function/method).
+ The ``@overload``-decorated definitions are for the benefit of the
+ type checker only, since they will be overwritten by the
+ non-``@overload``-decorated definition, while the latter is used at
+ runtime but should be ignored by a type checker. At runtime, calling
+ a ``@overload``-decorated function directly will raise
+ ``NotImplementedError``. An example of overload that gives a more
+ precise type than can be expressed using a union or a type variable::
+
+ @overload
+ def process(response: None) -> None:
+ ...
+ @overload
+ def process(response: int) -> Tuple[int, str]:
+ ...
+ @overload
+ def process(response: bytes) -> str:
+ ...
+ def process(response):
+ <actual implementation>
+
+ See :pep:`484` for details and comparison with other typing semantics.
+
.. decorator:: no_type_check(arg)
Decorator to indicate that annotations are not type hints.
@@ -785,3 +847,40 @@
This wraps the decorator with something that wraps the decorated
function in :func:`no_type_check`.
+
+.. data:: ClassVar
+
+ Special type construct to mark class variables.
+
+ As introduced in :pep:`526`, a variable annotation wrapped in ClassVar
+ indicates that a given attribute is intended to be used as a class variable
+ and should not be set on instances of that class. Usage::
+
+ class Starship:
+ stats: ClassVar[Dict[str, int]] = {} # class variable
+ damage: int = 10 # instance variable
+
+ ClassVar accepts only types and cannot be further subscribed.
+
+ ClassVar is not a class itself, and should not
+ be used with isinstance() or issubclass(). Note that ClassVar
+ does not change Python runtime behavior, it can be used by
+ 3rd party type checkers, so that the following code will
+ flagged as an error by those::
+
+ enterprise_d = Starship(3000)
+ enterprise_d.stats = {} # Error, setting class variable on instance
+ Starship.stats = {} # This is OK
+
+ .. versionadded:: 3.6
+
+.. data:: TYPE_CHECKING
+
+ A special constant that is assumed to be ``True`` by 3rd party static
+ type checkers. It is ``False`` at runtime. Usage::
+
+ if TYPE_CHECKING:
+ import expensive_mod
+
+ def fun():
+ local_var: expensive_mod.some_type = other_fun()
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list