54

Python 3.x supports (optional) function annotations:

def add_ints(x:int, y:int) -> int :
    return x+y

I sometimes encounter problems as to how to represent a given "type" can be represented, and this time, I have a function that returns a generator:

def myfunc(x: [int]) -> "generator that returns ints":
    #                     ^~~~~~~~~~~~~~~~~~~~~~~~~~
    return (n for n in x if n%2 == 0)

How should I annotate the return value? Is there any reference I can consult to?

4
  • Specifically what are you trying to accomplish by adding this annotation, Python seems to require nothing save that it be a valid expression, and does not use it internally. There don't seem to be guidelines or standards, so I would just do whatever is easiest for your case.
    – KSab
    Dec 3, 2014 at 5:37
  • @KSab Thank you for the comment. Knowing the absence of guidelines is a good start for me... Although python does not use annotations internally, invalid expressions are caught, so I can't just -> generator(int) without making it a string.
    – Yosh
    Dec 3, 2014 at 5:55
  • I suppose you could use types.GeneratorType (see docs.python.org/2/library/types.html), but you can't specify that it is a generator of ints (Python's generators can return multiple types anyway). If you are just doing this for your own type-checking I don't see any reason not to use a string identifier or maybe a global variable.
    – KSab
    Dec 3, 2014 at 6:04
  • types.GeneratorType seems to be what I was looking for (Why didn't I search for that!). Thanks for suggesting using string or variables too, I just wasn't certain it can be acceptable at all. Will you spare some more time and post that as an answer, so that I can accept it?
    – Yosh
    Dec 3, 2014 at 6:15

2 Answers 2

64

While Generator[x, y, z] exists, most of the time, you might want to use the less verbose Iterator:

def fn(x: int) -> Iterator[int]:
    return (n for n in range(x) if n%2 == 0)

Also works for yield

def fn(x: int) -> Iterator[int]:
    for n in range(x):
        yield n
4
  • This is a very good answer, depend on the minimum. Mar 26, 2021 at 10:52
  • 1
    Right, 99% of the time, "generator" is an implementation detail, and the public return type is "iterator". Very rarely do you actually want the caller to know you used generators to implement the feature. Oct 16, 2021 at 2:01
  • 2
    You can go even more abstract and declare the return type to be an Iterable, since all iterators should have an __iter__ method (that returns itself).
    – Blckknght
    Oct 16, 2021 at 2:02
  • @Blckknght. I think Iterator is better as it is more specific. With Iterable, calling next(fn(1)) would fail type checking with: Iterable do not have __next__ method Jan 31 at 18:02
47

The typing module defines the Generator type, which you can use like:

Generator[yield_type, send_type, return_type] 

See also PEP 0484.

3
  • What about cases where generator doesn't have send type or return type? The PEP isn't clear on that.
    – z33k
    Sep 10, 2019 at 11:57
  • 9
    @z33k "If your generator will only yield values, set the SendType and ReturnType to None" - from Generator doc
    – zvone
    Oct 5, 2019 at 20:41
  • 3
    Using an Iterator is much simpler, see Conchylicultor's answer
    – k107
    Aug 9, 2020 at 21:39

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.