`generator.close()` never raises `GeneratorExit`

[hyperkai]

Bug report

Bug description:

The doc of generator.close() says as shown below:

Raises a GeneratorExit at the point where the generator function was paused.

But generator.close() never raises GeneratorExit as shown below:

def func():
    yield 'Hello'
    yield 'World'

v = func()

print(v.close()) # None
print(v.close()) # None

def func():
    yield 'Hello'
    yield 'World'

v = func()

print(next(v)) # Hello

print(v.close()) # None
print(v.close()) # None

def func():
    yield 'Hello'
    yield 'World'

v = func()

print(next(v)) # Hello
print(next(v)) # World

print(v.close()) # None
print(v.close()) # None

def func():
    yield 'Hello'
    yield 'World'

v = func()

print(v.close()) # None

print(next(v)) # StopIteration

def func():
    yield 'Hello'
    yield 'World'

v = func()

print(next(v)) # Hello

print(v.close()) # None

print(next(v)) # StopIteration

CPython versions tested on:

3.13

Operating systems tested on:

Windows

Linked PRs

• gh-135110: Fix misleading generator.close() documentation #135152

[ZeroIntensity]

generator.close() sends the GeneratorExit to the yield inside the generator, not to caller of close. For example:

def a():
    try:
        yield "123"
    except GeneratorExit:
        print("gotcha!")

gen = a()
next(gen)
gen.close()  # gotcha!

Do you have any suggestions to make the documentation clearer?

[ryan-duve]

I think it's also helpful to emphasize this sentence later in the paragraph:

If the generator function is already closed, or raises GeneratorExit (by not catching the exception), close() returns None.