121

I'm trying to write a :rtype: type hint for a generator function. What is the type it returns?

For example, say I have this functions which yields strings:

def read_text_file(fn):
    """
    Yields the lines of the text file one by one.
    :param fn: Path of text file to read.
    :type fn: str
    :rtype: ???????????????? <======================= what goes here?
    """
    with open(fn, 'rt') as text_file:
        for line in text_file:
            yield line

The return type isn't just a string, it's some kind of iterable of strings? So I can't just write :rtype: str. What's the right hint?

8
  • returns a generator with strings Apr 27, 2017 at 13:19
  • 1
    Looks like you're not asking for a type hint but a docstring insertion for :rtype: Apr 27, 2017 at 13:21
  • 1
    People mark as duplicate without even reading the question. Sigh...
    – Wood
    May 28, 2019 at 16:08
  • @Wood Look again... May 29, 2019 at 7:10
  • 1
    @Jean-FrançoisCorbett The other question asks for the type annotation. This one asks for the docstring insertion for :rtype:. They are different things.
    – Wood
    May 29, 2019 at 8:36

3 Answers 3

131

Generator

Generator[str, None, None] or Iterator[str]

Before python 3.9:

from typing important Generator

python 3.9 and forward:

from collections.abc import Generator
3
  • 6
    Is there a new answer now that Python 3.9 supports more complex type hints?
    – Nathan Dai
    Sep 13, 2021 at 5:54
  • @NathanDai In Python 3.9 the syntax is basically the same, you just import the Generator class from collections.abc. See my answer for the details. May 2, 2022 at 8:59
  • 1
    Furthermore, from Python 3.9 typing.Generator is deprecated in favour of collections.abc.Generator.
    – 101
    Nov 30, 2022 at 8:37
79

As of Python 3.9, you can annotate a generator using the Generator[YieldType, SendType, ReturnType] generic type from collections.abc. For example:

from collections.abc import Generator

def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'

In earlier versions of Python you can import the Generator class from the typing module. Alternatively, Iterable[YieldType] or Iterator[YieldType] from typing can be used.

2
  • What's the difference between Iterator and Iterable when using for type hinting the yield action? Jun 30, 2022 at 6:58
  • 1
    @DanielLavedoniodeLima I guess, Iterable is more generic, while Iterator indicates that the result can be iterated only once. Jun 30, 2022 at 11:19
1

Comparing Iterator with Generator...

The docs define collections.abc.Generator as an "ABC for generator classes that implement ... the send(), throw() and close() methods".

So I use collections.abc.Iterator[ReturnType] for a 'plain' generator, and reserve collections.abc.Generator for cases where I have implemented send()/throw()/close().

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.