[Python-checkins] cpython (3.5): Add typing.Generator docs, by Michael Lee.

[guido.van.rossum]

https://hg.python.org/cpython/rev/b5403f416836
changeset:   102541:b5403f416836
branch:      3.5
parent:      102539:42d84513c3f0
user:        Guido van Rossum <guido at python.org>
date:        Fri Aug 05 12:56:09 2016 -0700
summary:
  Add typing.Generator docs, by Michael Lee.

files:
  Doc/library/typing.rst |  29 +++++++++++++++++++++++++++++
  1 files changed, 29 insertions(+), 0 deletions(-)


diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -556,6 +556,35 @@
 
 .. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])
 
+   A generator can be annotated by the generic type
+   ``Generator[YieldType, SendType, ReturnType]``. For example::
+
+      def echo_round() -> Generator[int, float, str]:
+          sent = yield 0
+          while sent >= 0:
+              sent = yield round(sent)
+          return 'Done'
+
+   Note that unlike many other generics in the typing module, the ``SendType``
+   of :class:`Generator` behaves contravariantly, not covariantly or
+   invariantly.
+
+   If your generator will only yield values, set the ``SendType`` and
+   ``ReturnType`` to ``None``::
+
+      def infinite_stream(start: int) -> Generator[int, None, None]:
+          while True:
+              yield start
+              start += 1
+
+   Alternatively, annotate your generator as having a return type of
+   ``Iterator[YieldType]``::
+
+      def infinite_stream(start: int) -> Iterator[int]:
+          while True:
+              yield start
+              start += 1
+
 .. class:: io
 
    Wrapper namespace for I/O stream types.

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