Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Improve documentation for annotating generator functions #11623

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hauntsaninja merged 5 commits into from
Nov 27, 2021
Merged

Improve documentation for annotating generator functions #11623

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
97167d0
Improve documentation for annotating generator functions
AlexWaygood Nov 26, 2021
c5a7c31
Address review
AlexWaygood Nov 26, 2021
827ae8b
Update docs/source/kinds_of_types.rst
hauntsaninja Nov 26, 2021
d1b75a0
Update docs/source/kinds_of_types.rst
hauntsaninja Nov 26, 2021
9c84d21
Make more succinct, addressing review
AlexWaygood Nov 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions docs/source/kinds_of_types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -721,18 +721,29 @@ For more details, see :ref:`type-variable-value-restriction`.
Generators
**********

A basic generator that only yields values can be annotated as having a return
A basic generator that only yields values can be succinctly annotated as having a return
type of either :py:class:`Iterator[YieldType] <typing.Iterator>` or :py:class:`Iterable[YieldType] <typing.Iterable>`. For example:
Comment thread
AlexWaygood marked this conversation as resolved.

.. code-block:: python

def squares(n: int) -> Iterator[int]:
for i in range(n):
yield i * i

A good rule of thumb is to annotate functions with the most specific return
type possible. However, you should also take care to avoid leaking implementation
details into a function's public API. In keeping with these two principles, prefer
:py:class:`Iterator[YieldType] <typing.Iterator>` over
:py:class:`Iterable[YieldType] <typing.Iterable>` as the return-type annotation for a
generator function, as it lets mypy know that users are able to call :py:func:`next` on
the object returned by the function. Nonetheless, bear in mind that ``Iterable`` may
sometimes be the better option, if you consider it an implementation detail that
``next()`` can be called on the object returned by your function.

If you want your generator to accept values via the :py:meth:`~generator.send` method or return
a value, you should use the
:py:class:`Generator[YieldType, SendType, ReturnType] <typing.Generator>` generic type instead. For example:
a value, on the other hand, you should use the
:py:class:`Generator[YieldType, SendType, ReturnType] <typing.Generator>` generic type instead of
either ``Iterator`` or ``Iterable``. For example:

.. code-block:: python

Expand All @@ -755,7 +766,7 @@ annotated the first example as the following:
for i in range(n):
yield i * i

This is slightly different from using ``Iterable[int]`` or ``Iterator[int]``,
This is slightly different from using ``Iterator[int]`` or ``Iterable[int]``,
since generators have :py:meth:`~generator.close`, :py:meth:`~generator.send`, and :py:meth:`~generator.throw` methods that
generic iterables don't. If you will call these methods on the returned
generator, use the :py:class:`~typing.Generator` type instead of :py:class:`~typing.Iterable` or :py:class:`~typing.Iterator`.
generic iterators and iterables don't. If you plan to call these methods on the returned
generator, use the :py:class:`~typing.Generator` type instead of :py:class:`~typing.Iterator` or :py:class:`~typing.Iterable`.