From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Sat, 8 Apr 2017 16:09:14 +0000 (-0700)
Subject: Improvements to typing documentation (#967)
X-Git-Tag: v3.7.0a1~993
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=45d22c256bce3afcf57f49032a6b20fdec4f26ad;p=python

Improvements to typing documentation (#967)

Documents a few omitted classes and adds NamedTuple methods.
---

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index d130e1759d..2cfc37f695 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -508,6 +508,14 @@ The module defines the following classes, functions and decorators:
 
     An ABC with one abstract method ``__float__``.
 
+.. class:: SupportsComplex
+
+    An ABC with one abstract method ``__complex__``.
+
+.. class:: SupportsBytes
+
+    An ABC with one abstract method ``__bytes__``.
+
 .. class:: SupportsAbs
 
     An ABC with one abstract method ``__abs__`` that is covariant
@@ -658,7 +666,19 @@ The module defines the following classes, functions and decorators:
 
 .. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
 
-   A generic version of :class:`collections.defaultdict`
+   A generic version of :class:`collections.defaultdict`.
+
+.. class:: Counter(collections.Counter, Dict[T, int])
+
+   A generic version of :class:`collections.Counter`.
+
+   .. versionadded:: 3.6.1
+
+.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT])
+
+   A generic version of :class:`collections.ChainMap`.
+
+   .. versionadded:: 3.6.1
 
 .. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
 
@@ -742,9 +762,12 @@ The module defines the following classes, functions and decorators:
 
    This defines the generic type ``IO[AnyStr]`` and aliases ``TextIO``
    and ``BinaryIO`` for respectively ``IO[str]`` and ``IO[bytes]``.
-   These representing the types of I/O streams such as returned by
+   These represent the types of I/O streams such as returned by
    :func:`open`.
 
+   These types are also accessible directly as ``typing.IO``,
+   ``typing.TextIO``, and ``typing.BinaryIO``.
+
 .. class:: re
 
    Wrapper namespace for regular expression matching types.
@@ -756,6 +779,9 @@ The module defines the following classes, functions and decorators:
    ``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or
    ``Match[bytes]``.
 
+   These types are also accessible directly as ``typing.Pattern``
+   and ``typing.Match``.
+
 .. class:: NamedTuple
 
    Typed version of namedtuple.
@@ -782,10 +808,20 @@ The module defines the following classes, functions and decorators:
    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
+   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.)
 
+   ``NamedTuple`` subclasses can also have docstrings and methods::
+
+      class Employee(NamedTuple):
+          """Represents an employee."""
+          name: str
+          id: int = 3
+
+          def __repr__(self) -> str:
+              return f'<Employee {self.name}, id={self.id}>'
+
    Backward-compatible usage::
 
        Employee = NamedTuple('Employee', [('name', str), ('id', int)])
@@ -794,7 +830,7 @@ The module defines the following classes, functions and decorators:
       Added support for :pep:`526` variable annotation syntax.
 
    .. versionchanged:: 3.6.1
-      Added support for default values.
+      Added support for default values, methods, and docstrings.
 
 .. function:: NewType(typ)
 
@@ -972,9 +1008,9 @@ The module defines the following classes, functions and decorators:
 
    :data:`ClassVar` is not a class itself, and should not
    be used with :func:`isinstance` or :func:`issubclass`.
-   Note that :data:`ClassVar` does not change Python runtime behavior;
-   it can be used by 3rd party type checkers, so that the following
-   code might flagged as an error by those::
+   :data:`ClassVar` does not change Python runtime behavior, but
+   it can be used by third-party type checkers. For example, a type checker
+   might flag the following code as an error::
 
       enterprise_d = Starship(3000)
       enterprise_d.stats = {} # Error, setting class variable on instance