From f75578dbb57929a2e2787f4dd28e051121343030 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 2 Apr 2017 20:45:32 -0700 Subject: [PATCH 1/4] Improvements to typing documentation Documents a few omitted classes and adds NamedTuple methods. --- Doc/library/typing.rst | 44 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d130e1759d8f59..0583ae835a0079 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,8 +762,11 @@ 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 @@ -755,6 +778,9 @@ The module defines the following classes, functions and decorators: are generic in ``AnyStr`` and can be made specific by writing ``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or ``Match[bytes]``. + + These types are also accessible directly as ``typing.Pattern`` + and ``typing.Match``. .. class:: NamedTuple @@ -782,9 +808,19 @@ 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.) + + Classes can also have docstrings and methods:: + + class Employee(NamedTuple): + """Represents an employee.""" + name: str + id: int = 3 + + def __repr__(self) -> str: + return f'' Backward-compatible usage:: @@ -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) From b268bb4202a0a4da1ad121630296da06d8db5d4d Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 2 Apr 2017 20:48:42 -0700 Subject: [PATCH 2/4] clarify statement --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 0583ae835a0079..7d90ddc7c93a72 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -812,7 +812,7 @@ The module defines the following classes, functions and decorators: mapping field names to default values. (The field names are in the ``_fields`` attribute, which is part of the namedtuple API.) - Classes can also have docstrings and methods:: + ``NamedTuple`` subclasses can also have docstrings and methods:: class Employee(NamedTuple): """Represents an employee.""" From de67ab3eb4c7ee36bfff648df95dd67cf7c58046 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 2 Apr 2017 20:54:52 -0700 Subject: [PATCH 3/4] remove trailing whitespace --- Doc/library/typing.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 7d90ddc7c93a72..4102215044205f 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -671,13 +671,13 @@ The module defines the following classes, functions and decorators: .. 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]) @@ -764,7 +764,7 @@ The module defines the following classes, functions and decorators: and ``BinaryIO`` for respectively ``IO[str]`` and ``IO[bytes]``. 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``. @@ -778,7 +778,7 @@ The module defines the following classes, functions and decorators: are generic in ``AnyStr`` and can be made specific by writing ``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or ``Match[bytes]``. - + These types are also accessible directly as ``typing.Pattern`` and ``typing.Match``. @@ -811,14 +811,14 @@ The module defines the following classes, functions and decorators: 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'' From 4a9cda13d588c493e97e0a2b247e445f6c546062 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 2 Apr 2017 21:00:07 -0700 Subject: [PATCH 4/4] fix ClassVar wording --- Doc/library/typing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 4102215044205f..2cfc37f695ef2d 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1008,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