gh-104770: Let generator.close() return value

[ntessore]

This changeset alters generator.close() to return the value of a StopIteration it encounters. Conceptually, the change is simple: instead of lumping StopIteration in with GeneratorExit and ignoring it, the exception is handled specially and its value returned.

Practically, handling the exception is a little awkward because no high-level API exists (afaict) to retrieve the value of a StopIteration. I would be happy for any pointers on how to handle this better, if possible.

• Issue: Let generator.close() return StopIteration.value #104770

---

📚 Documentation preview 📚: https://cpython-previews--104771.org.readthedocs.build/

[bedevere-bot]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-bot]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

[gvanrossum]

I'm also asking @iritkatriel to review -- I'm not sure if poking at tstate->current_exception is the right way to access the current exception. Maybe the brand new PyPyErr_GetRaisedException() is the API to use? (Then you don't even need to get the tstate).

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[ntessore]

I have made the requested changes; please review again.

In the docs, I made the wording of the "returns return value" situation sound as natural as I could, but it might need more polishing.

I didn't know about PyErr_GetRaisedException(), thanks! That fits perfectly here. I don't suppose there's a brand new API to extract the value from an exception?

[bedevere-bot]

Thanks for making the requested changes!

@gvanrossum: please review the changes made to this pull request.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[ntessore]

Thanks @iritkatriel, that is much better. I have made the requested changes; please review again.

[bedevere-bot]

Thanks for making the requested changes!

@gvanrossum, @iritkatriel: please review the changes made to this pull request.

[gvanrossum]

I'll leave the rest of the review to Irit.

[iritkatriel]

Code looks fine, a couple of comments on documentation.

#104771 (comment)

[gvanrossum]

Fantastic! I will merge now.

[ntessore]

Thanks again Irit and Guido for your help and patience!