Python 3.5 Iterator[] annotation

They offer a standardized Iterator[] syntax for this as documented at: https://docs.python.org/3/library/typing.html#typing.Generator

Before Python 3, I recommend that you use this syntax to make it easier to port later on:

def f():
    """
    :rtype: Iterator[:class:`SomeClass`]
    """
    yield SomeClass()

And after Python 3, use https://pypi.python.org/pypi/sphinx-autodoc-annotation with syntax:

from typing import Iterator
def f() -> Iterator[SomeClass]:
    yield SomeClass()

I would consider @return to be appropriate in this case because the function actually returns an iterator object with a next or send method. The validity of the statement x = my_generator(from=3) implies that my_generator really does return something. It merely does so without using the return statement to do it.

In some ways, functions containing a yield statement or expression behave like classes, because they are factories that return objects with predictable properties. However, because generator functions can themselves be declared and invoked as instance methods, I do not think of them as classes.