1 files changed, 55 insertions, 13 deletions
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 8da71b64a7..6c8982ba74 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -8,10 +8,17 @@
 
 **Source code:** :source:`Lib/typing.py`
 
+.. note::
+
+   The typing module has been included in the standard library on a
+   :term:`provisional basis <provisional api>`. New features might
+   be added and API may change even between minor releases if deemed
+   necessary by the core developers.
+
 --------------
 
-This module supports type hints as specified by :pep:`484`.  The most
-fundamental support consists of the types :data:`Any`, :data:`Union`,
+This module supports type hints as specified by :pep:`484` and :pep:`526`.
+The most fundamental support consists of the types :data:`Any`, :data:`Union`,
 :data:`Tuple`, :data:`Callable`, :class:`TypeVar`, and
 :class:`Generic`.  For full specification please see :pep:`484`.  For
 a simplified introduction to type hints see :pep:`483`.
@@ -523,7 +530,13 @@ The module defines the following classes, functions and decorators:
 
    An alias to :class:`collections.abc.Sized`
 
-.. class:: AbstractSet(Sized, Iterable[T_co], Container[T_co])
+.. class:: Collection(Sized, Iterable[T_co], Container[T_co])
+
+   A generic version of :class:`collections.abc.Collection`
+
+   .. versionadded:: 3.6
+
+.. class:: AbstractSet(Sized, Collection[T_co])
 
     A generic version of :class:`collections.abc.Set`.
 
@@ -531,7 +544,7 @@ The module defines the following classes, functions and decorators:
 
     A generic version of :class:`collections.abc.MutableSet`.
 
-.. class:: Mapping(Sized, Iterable[KT], Container[KT], Generic[VT_co])
+.. class:: Mapping(Sized, Collection[KT], Generic[VT_co])
 
     A generic version of :class:`collections.abc.Mapping`.
 
@@ -539,7 +552,7 @@ The module defines the following classes, functions and decorators:
 
     A generic version of :class:`collections.abc.MutableMapping`.
 
-.. class:: Sequence(Sized, Iterable[T_co], Container[T_co])
+.. class:: Sequence(Reversible[T_co], Collection[T_co])
 
     A generic version of :class:`collections.abc.Sequence`.
 
@@ -627,6 +640,12 @@ The module defines the following classes, functions and decorators:
 
    A generic version of :class:`collections.abc.AsyncIterator`.
 
+.. class:: ContextManager(Generic[T_co])
+
+   A generic version of :class:`contextlib.AbstractContextManager`.
+
+   .. versionadded:: 3.6
+
 .. class:: Dict(dict, MutableMapping[KT, VT])
 
    A generic version of :class:`dict`.
@@ -735,22 +754,45 @@ The module defines the following classes, functions and decorators:
    ``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or
    ``Match[bytes]``.
 
-.. function:: NamedTuple(typename, fields)
+.. class:: NamedTuple
 
    Typed version of namedtuple.
 
    Usage::
 
-       Employee = typing.NamedTuple('Employee', [('name', str), ('id', int)])
+       class Employee(NamedTuple):
+           name: str
+           id: int
 
    This is equivalent to::
 
        Employee = collections.namedtuple('Employee', ['name', 'id'])
 
-   The resulting class has one extra attribute: _field_types,
-   giving a dict mapping field names to types.  (The field names
-   are in the _fields attribute, which is part of the namedtuple
-   API.)
+   To give a field a default value, you can assign to it in the class body::
+
+      class Employee(NamedTuple):
+          name: str
+          id: int = 3
+
+      employee = Employee('Guido')
+      assert employee.id == 3
+
+   Fields with a default value must come after any fields without a default.
+
+   The resulting class has two extra attributes: ``_field_types``,
+   giving a dict mapping field names to types, and ``field_defaults``, a dict
+   mapping field names to default values.  (The field names are in the
+   ``_fields`` attribute, which is part of the namedtuple API.)
+
+   Backward-compatible usage::
+
+       Employee = NamedTuple('Employee', [('name', str), ('id', int)])
+
+   .. versionchanged:: 3.6
+      Added support for :pep:`526` variable annotation syntax.
+
+   .. versionchanged:: 3.6.1
+      Added support for default values.
 
 .. function:: NewType(typ)
 
@@ -921,8 +963,8 @@ The module defines the following classes, functions and decorators:
    and should not be set on instances of that class. Usage::
 
       class Starship:
-          stats = {}  # type: ClassVar[Dict[str, int]] # class variable
-          damage = 10 # type: int                      # instance variable
+          stats: ClassVar[Dict[str, int]] = {} # class variable
+          damage: int = 10                     # instance variable
 
    :data:`ClassVar` accepts only types and cannot be further subscribed.