[Python-checkins] cpython (3.5): Update typing docs based on a patch by Daniel Andrade Groppe.

[guido.van.rossum]

https://hg.python.org/cpython/rev/a9153eca5c72
changeset:   97843:a9153eca5c72
branch:      3.5
user:        Guido van Rossum <guido at dropbox.com>
date:        Wed Sep 09 12:01:36 2015 -0700
summary:
  Update typing docs based on a patch by Daniel Andrade Groppe.

files:
  Doc/library/typing.rst |  67 +++++++++++++++++++++++------
  1 files changed, 53 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
@@ -68,7 +68,7 @@
                        overrides: Mapping[str, str]) -> None: ...
 
 Generics can be parametrized by using a new factory available in typing
-called TypeVar.
+called :class:`TypeVar`.
 
 .. code-block:: python
 
@@ -145,7 +145,7 @@
    class Pair(Generic[T, T]):   # INVALID
        ...
 
-You can use multiple inheritance with `Generic`::
+You can use multiple inheritance with :class:`Generic`::
 
    from typing import TypeVar, Generic, Sized
 
@@ -154,6 +154,17 @@
    class LinkedList(Sized, Generic[T]):
        ...
 
+When inheriting from generic classes, some type variables could fixed::
+
+    from typing import TypeVar, Mapping
+
+    T = TypeVar('T')
+
+    class MyDict(Mapping[str, T]):
+        ...
+
+In this case ``MyDict`` has a single parameter, ``T``.
+
 Subclassing a generic class without specifying type parameters assumes
 :class:`Any` for each position. In the following example, ``MyIterable`` is
 not generic but implicitly inherits from ``Iterable[Any]``::
@@ -162,7 +173,11 @@
 
    class MyIterable(Iterable): # Same as Iterable[Any]
 
-Generic metaclasses are not supported.
+The metaclass used by :class:`Generic` is a subclass of :class:`abc.ABCMeta`.
+A generic class can be an ABC by including abstract methods or properties,
+and generic classes can also have ABCs as base classes without a metaclass
+conflict.  Generic metaclasses are not supported.
+
 
 The :class:`Any` type
 ---------------------
@@ -178,15 +193,6 @@
 on it, and a value of type :class:`Any` can be assigned to a variable (or used
 as a return value) of a more constrained type.
 
-Default argument values
------------------------
-
-Use a literal ellipsis ``...`` to declare an argument as having a default value::
-
-   from typing import AnyStr
-
-   def foo(x: AnyStr, y: AnyStr = ...) -> AnyStr: ...
-
 
 Classes, functions, and decorators
 ----------------------------------
@@ -236,7 +242,11 @@
 
     Type variables may be marked covariant or contravariant by passing
     ``covariant=True`` or ``contravariant=True``.  See :pep:`484` for more
-    details.  By default type variables are invariant.
+    details.  By default type variables are invariant.  Alternatively,
+    a type variable may specify an upper bound using ``bound=<type>``.
+    This means that an actual type substituted (explicitly or implictly)
+    for the type variable must be a subclass of the boundary type,
+    see :pep:`484`.
 
 .. class:: Union
 
@@ -329,30 +339,59 @@
 
 .. class:: Iterable(Generic[T_co])
 
+    A generic version of the :class:`collections.abc.Iterable`.
+
 .. class:: Iterator(Iterable[T_co])
 
+    A generic version of the :class:`collections.abc.Iterator`.
+
 .. class:: SupportsInt
 
+    An ABC with one abstract method `__int__`.
+
 .. class:: SupportsFloat
 
+    An ABC with one abstract method `__float__`.
+
 .. class:: SupportsAbs
 
+    An ABC with one abstract method `__abs__` that is covariant
+    in its return type.
+
 .. class:: SupportsRound
 
+    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:: AbstractSet(Sized, Iterable[T_co], Container[T_co])
 
+    A generic version of :class:`collections.abc.Set`.
+
 .. class:: MutableSet(AbstractSet[T])
 
-.. class:: Mapping(Sized, Iterable[KT_co], Container[KT_co], Generic[KT_co, VT_co])
+    A generic version of :class:`collections.abc.MutableSet`.
+
+.. class:: Mapping(Sized, Iterable[KT], Container[KT], Generic[VT_co])
+
+    A generic version of :class:`collections.abc.Mapping`.
 
 .. class:: MutableMapping(Mapping[KT, VT])
 
+    A generic version of :class:`collections.abc.MutableMapping`.
+
 .. class:: Sequence(Sized, Iterable[T_co], Container[T_co])
 
+    A generic version of :class:`collections.abc.Sequence`.
+
 .. class:: MutableSequence(Sequence[T])
 
    A generic version of :class:`collections.abc.MutableSequence`.

-- 
Repository URL: https://hg.python.org/cpython