https://github.com/python/cpython/commit/902196d867a34cc154fa9c861c883e69232... commit: 902196d867a34cc154fa9c861c883e69232251c6 branch: 3.7 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: GitHub <noreply@github.com> date: 2019-01-04T06:20:19-08:00 summary: bpo-35631: Improve typing docs wrt abstract/concrete collection types (GH-11396) https://bugs.python.org/issue35631 (cherry picked from commit 31ec52a9afedd77e36a3ddc31c4c45664b8ac410) Co-authored-by: Ville Skyttä <ville.skytta@iki.fi> files: M Doc/library/typing.rst diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 0f37fc60896f..1e6dcccc1ffe 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -50,20 +50,20 @@ A type alias is defined by assigning the type to the alias. In this example, Type aliases are useful for simplifying complex type signatures. For example:: - from typing import Dict, Tuple, List + from typing import Dict, Tuple, Sequence ConnectionOptions = Dict[str, str] Address = Tuple[str, int] Server = Tuple[Address, ConnectionOptions] - def broadcast_message(message: str, servers: List[Server]) -> None: + def broadcast_message(message: str, servers: Sequence[Server]) -> None: ... # The static type checker will treat the previous type signature as # being exactly equivalent to this one. def broadcast_message( message: str, - servers: List[Tuple[Tuple[str, int], Dict[str, str]]]) -> None: + servers: Sequence[Tuple[Tuple[str, int], Dict[str, str]]]) -> None: ... Note that ``None`` as a type hint is a special case and is replaced by @@ -568,6 +568,10 @@ The module defines the following classes, functions and decorators: .. class:: Mapping(Sized, Collection[KT], Generic[VT_co]) A generic version of :class:`collections.abc.Mapping`. + This type can be used as follows:: + + def get_position_in_index(word_list: Mapping[str, int], word: str) -> int: + return word_list[word] .. class:: MutableMapping(Mapping[KT, VT]) @@ -601,8 +605,8 @@ The module defines the following classes, functions and decorators: Generic version of :class:`list`. Useful for annotating return types. To annotate arguments it is preferred - to use abstract collection types such as :class:`Mapping`, :class:`Sequence`, - or :class:`AbstractSet`. + to use an abstract collection type such as :class:`Sequence` or + :class:`Iterable`. This type may be used as follows:: @@ -617,6 +621,8 @@ The module defines the following classes, functions and decorators: .. class:: Set(set, MutableSet[T]) A generic version of :class:`builtins.set <set>`. + Useful for annotating return types. To annotate arguments it is preferred + to use an abstract collection type such as :class:`AbstractSet`. .. class:: FrozenSet(frozenset, AbstractSet[T_co]) @@ -678,10 +684,13 @@ The module defines the following classes, functions and decorators: .. class:: Dict(dict, MutableMapping[KT, VT]) A generic version of :class:`dict`. - The usage of this type is as follows:: + Useful for annotating return types. To annotate arguments it is preferred + to use an abstract collection type such as :class:`Mapping`. - def get_position_in_index(word_list: Dict[str, int], word: str) -> int: - return word_list[word] + This type can be used as follows:: + + def count_words(text: str) -> Dict[str, int]: + ... .. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])