[Python-checkins] bpo-35631: Improve typing docs wrt abstract/concrete collection types (GH-11396)
Miss Islington (bot)
webhook-mailer at python.org
Fri Jan 4 09:20:22 EST 2019
https://github.com/python/cpython/commit/902196d867a34cc154fa9c861c883e69232251c6
commit: 902196d867a34cc154fa9c861c883e69232251c6
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at 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 at 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])
More information about the Python-checkins
mailing list