Feature or enhancement

Change theclose() method of generators to return the value ofStopIteration.

Pitch

If a generator handles theGeneratorExit thrown byclose(), it can exit gracefully, raisingStopIteration with its return value.

deff():try:yieldexceptGeneratorExit:passreturn0g=f()g.send(None)g.close()# StopIteration handled by close()

TheStopIteration is handled byclose(), but the return value is currently discarded, andclose() always returnsNone.

The proposed change is to letclose() return the value of aStopIteration it encounters after a graceful generator exit.

Every other case, including errors thrown betweenexcept GeneratorExit andreturn, is already handled byclose() and would remain unchanged. This includes repeated calls toclose(): Only the first such call might cause a generator to exit gracefully, after which it cannot raiseStopIteration any longer.

The change enables more natural use of generators as "pipelines" that process input data until ended. As a trivial example of the functionality, consider this computer of averages:

defaverager():n=0sum=0.whileTrue:try:x=yieldnexceptGeneratorExit:breakn+=1sum+=xmean=sum/nreturnmeanavg=averager()avg.send(None)fornumberinget_some_numbers():avg.send(number)mean=avg.close()

The generator processes data in an infinite loop. Once the controlling process terminates processing, the generator performs post-processing, and returns a final result. Without the return value ofclose(), there is no intrinsic way of obtaining such a post-processed result.

Previous discussion

Discourse thread:Let generator.close() return StopIteration.value

Linked PRs

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