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.

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

Mention distinction between Generator and Iterator #4424

Merged
merged 2 commits into from Jan 5, 2018

Conversation

Projects
None yet
2 participants
@carljm
Contributor

carljm commented Jan 3, 2018

As seen in python/typeshed#1806, Generator[..., None, None] is not quite equivalent to Iterator[...], due to the close() method on generators. In most cases this probably doesn't matter, since the close() method is infrequently used, so I've left the basic structure of the docs the same (recommending Iterator[...] first for simple generators). But it's at least worth a mention.

Mention distinction between Generator and Iterator
As seen in python/typeshed#1806, `Generator[..., None, None]` is not quite equivalent to `Iterator[...]`, due to the `close()` method on generators. In most cases this probably doesn't matter, since the `close()` method is infrequently used, so I've left the basic structure of the docs the same (recommending `Iterator[...]` first for simple generators). But it's at least worth a mention.
@ilevkivskyi

I am wondering maybe this should be in "Common issues" section. I have seen this Generator vs Iterator question few times before.

@@ -986,6 +986,9 @@ annotated the first example as the following:
def squares(n: int) -> Generator[int, None, None]:
for i in range(n):
yield i * i
This is slightly different from using ``Iterable[int]`` or ``Iterator[int]``,
since generators have a ``close()`` method that generic iterables don't.

This comment has been minimized.

@ilevkivskyi

ilevkivskyi Jan 3, 2018

Collaborator

Generators have also throw and send, maybe you could say explicitly that if one wants to call send, throw or close, then one should use Generator[T, None, None] (this can actually be a generic type alias). Maybe you can illustrate this with a short example, like:

x: Iterator[int]
x.send(None) # Error!
x.close() # Error!
y: Generator[int, None, None]
... # etc.
@carljm

This comment has been minimized.

Contributor

carljm commented Jan 5, 2018

I think it should definitely be mentioned here regardless; if you also want it mentioned in Common Issues I can add that.

I added mention of send() and throw(). I don't feel like this note is important enough to warrant its own example; I think the added text is clear enough. If you feel strongly that an example is needed, let me know and I will add it.

@ilevkivskyi

OK, I like how it is formulated now. If there are no objections from others, then I will merge this soon.

@ilevkivskyi ilevkivskyi merged commit 3edf07b into python:master Jan 5, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment