How Python's generator.send() Works

Many Python developers learn generators as one-way pipes: the function yields a value, the caller receives it, repeat until exhaustion. That mental model is incomplete. Since Python 2.5, generators have had a second channel — a way to push data back in while execution is paused. That channel is .send(), and understanding it changes how you think about what a generator actually is.

The confusion around .send() is almost always the same confusion at its root: people treat yield as a statement that pauses and emits, full stop. But yield in Python is an expression — it both emits a value outward and resolves to a value inward, and .send() is what controls that inward resolution. This article explains exactly how that works, where it came from, what goes wrong when you skip the priming step, and where the pattern still belongs today.

Generators Were Always One-Way — Until Python 2.5

Python introduced generators in version 2.2 via PEP 255. The design was clean and deliberate: a generator function suspends at a yield statement, returns the yielded value to the caller, and resumes from that exact point when next() is called again. All local state — variable bindings, the instruction pointer, the internal stack — is preserved across the suspension. This made generators excellent lazy iterators: you could produce sequences of values on demand without building them all in memory at once.

What generators could not do was receive input after they started. Every call to next() resumed execution, but brought nothing with it. The generator could only observe its own internal state and whatever was captured in its closure. If you wanted it to behave differently based on external input, you had to encode that into the arguments passed at construction time. The communication was strictly one direction: generator to caller.

That limitation became a real problem as developers tried to use generators for more sophisticated tasks — simulations, event-driven pipelines, cooperative multitasking. The PEP 342 authors, Guido van Rossum and Phillip J. Eby, diagnosed the gap precisely. As stated in PEP 342, Python's generators were "almost coroutines — but not quite" because they allowed pausing execution to produce a value but provided no mechanism for passing values or exceptions back in when execution resumed.

The fix required two linked changes: making yield an expression rather than a pure statement, and adding a .send() method to the generator object. Both shipped together in Python 2.5, released in September 2006. The cumulative effect, as PEP 342 described it, was to turn generators from one-way producers of information into both producers and consumers — and in doing so, to turn them into proper coroutines.

How yield Became an Expression

Before Python 2.5, yield was a statement. You wrote yield some_value and that was the whole story: the value was emitted and execution paused. The statement had no return value because there was nothing to return — no channel existed through which the caller could inject anything.

PEP 342 changed yield into an expression. This is a meaningful distinction. An expression in Python produces a value. Statements do not. When yield became an expression, the syntax received = yield emitted_value became legal and meaningful: emitted_value is sent out to the caller, and whatever the caller injects back becomes the value that yield evaluates to — stored in received.

The PEP captures the conceptual flip precisely. As written in PEP 342: a yield expression is "like an inverted function call — the argument to yield is in fact returned (yielded) from the currently executing function, and the return value of yield is the argument passed in via send()." That inversion framing is the clearest single-sentence description of what .send() does. The generator's yield is both an outgoing return and an incoming parameter slot, depending on which side of the channel you are reading from.

The Python Language Reference formalizes the receive side: the value argument of .send() "becomes the result of the current yield expression." If no value is sent — if next() is called instead — the yield expression evaluates to None. That asymmetry is important and is the source of most confusion about .send().

The practical consequence of yield-as-expression is that a single yield point in your generator now does double duty simultaneously. It emits a value on the way out and receives a value on the way in. Those two actions happen at the same suspension point, which is why the timing of .send() is so important: you can only send into a yield that is currently waiting. You cannot send into thin air.

The Mechanics of .send() Step by Step

When you call gen.send(value), the following sequence happens in order inside CPython:

First, the generator's execution is resumed from the point where it is currently suspended — at a yield expression. Second, the value argument you passed becomes the result of that yield expression inside the generator's frame. Third, execution continues forward inside the generator until the next yield expression is reached. Fourth, the value following that next yield is returned to the caller as the return value of .send(). If no further yield is reached and the generator function returns, StopIteration is raised.

Here is a minimal example that makes each of these steps visible:

def two_way():
    print("Generator started")
    received = (yield "first yield")   # emits "first yield", waits
    print(f"Received: {received}")
    received2 = (yield "second yield") # emits "second yield", waits
    print(f"Received again: {received2}")
    # no more yields — StopIteration will be raised next

gen = two_way()

# Prime: advance to the first yield
out1 = next(gen)         # prints "Generator started"
print(out1)              # prints "first yield"

# Send a value in; generator resumes, "Hello" is the value of the yield expression
out2 = gen.send("Hello") # prints "Received: Hello"
print(out2)              # prints "second yield"

# Send again
try:
    gen.send("World")    # prints "Received again: World"
except StopIteration:
    print("Generator exhausted")

Trace through this carefully. The first next(gen) call advances execution to the first yield "first yield". At that point the generator is suspended: it has emitted "first yield" and is waiting at the yield expression. When gen.send("Hello") is called, "Hello" is injected as the value of that waiting yield expression — so received gets the string "Hello". Execution continues until the second yield "second yield", which emits "second yield" outward to the caller (the return value of .send()). The generator is now suspended again at the second yield. The final .send("World") injects "World" into that expression, prints the message, then the function ends with no further yields, raising StopIteration.

Build It Yourself: Writing a Two-Way Generator from Scratch

The section above described what .send() does. This section makes you do it. Follow each step in order, typing the code yourself rather than copying the finished version. The goal is to feel the execution hand-off, not just read about it.

You will need Python 3.x open in a terminal, REPL, or notebook. Each step builds on the previous one.

Step 1 — Write the generator function shell

Start with the function definition only. Do not add any logic yet. A generator function is just a regular function that contains at least one yield expression.

def greeter():
    pass

Calling greeter() right now returns a generator object immediately — Python sees the def keyword and notices that the function body will contain yield (it will in a moment), so it compiles it as a generator function. No code inside the function has run yet. Nothing runs until you advance the generator.

Step 2 — Add a yield expression that emits and receives

Replace pass with a single yield that emits a prompt and captures whatever the caller sends back. Wrap it in parentheses so the receive assignment is unambiguous.

def greeter():
    name = (yield "What is your name?")

Read this line carefully: "What is your name?" is the value emitted outward to the caller. name is the variable that will receive whatever the caller sends back. Both sides are wired through a single yield expression. Nothing has run yet — this is still just a definition.

Step 3 — Add a response yield

After the generator receives the name, it should emit a personalised greeting. Add a second yield that uses the received value:

def greeter():
    name = (yield "What is your name?")
    yield f"Hello, {name}!"

The function now has two suspension points. The first yields the prompt and waits. The second yields the greeting after the name has been received. After the second yield, the function ends — the next call to .send() will raise StopIteration.

Step 4 — Create the generator object

Call the function. Note that calling it does not run the body:

gen = greeter()
print(gen)   # <generator object greeter at 0x...>

You have a generator object. The body has not executed. The generator is in GEN_CREATED state — created, never started. If you tried to call gen.send("Alice") right now, you would get TypeError. Try it if you want to see it fail — then continue.

Step 5 — Prime the generator

Advance it to the first yield using next(). This runs the function body until it hits the first yield, suspends, and returns the yielded value to you:

prompt = next(gen)
print(prompt)   # What is your name?

What just happened: the generator ran from the top of the function body up to the first yield "What is your name?". It emitted that string, suspended, and is now waiting. The variable name inside the generator has no value yet — the yield expression has not resolved. The generator is now in GEN_SUSPENDED state.

Step 6 — Send a value in

Now call .send() with the name. This resumes the generator, injects your value as the result of the waiting yield expression, and runs until the next yield:

greeting = gen.send("Alice")
print(greeting)   # Hello, Alice!

Inside the generator: "Alice" became the resolved value of the yield expression, so name was assigned "Alice". Execution continued to the second yield f"Hello, {name}!", which emitted the greeting string and suspended again. gen.send("Alice") returned that string to you.

Step 7 — Handle the end of the generator

The generator is still suspended at the second yield. One more .send() will resume it, find no further yield, and raise StopIteration. Wrap it:

try:
    gen.send(None)   # resume from second yield; no more yields → StopIteration
except StopIteration:
    print("Generator finished.")

Step 8 — Put it together and extend it

Here is the complete version as it now stands, with the full call sequence in one block so you can see the whole picture at once:

def greeter():
    name = (yield "What is your name?")
    yield f"Hello, {name}!"

gen = greeter()
prompt   = next(gen)            # prime → "What is your name?"
greeting = gen.send("Alice")    # send name → "Hello, Alice!"
try:
    gen.send(None)              # no more yields → StopIteration
except StopIteration:
    print("Done.")

Now extend it yourself — or better yet, drive it live right here.

Why You Must Prime a Generator First

The rule is firm: you cannot call .send(non_None_value) on a generator that has not yet been advanced to its first yield. Attempting to do so raises TypeError: can't send non-None value to a just-started generator.

The reason is structural. When a generator object is first created, its code has not executed at all. There is no yield expression currently suspended and waiting to receive anything. The .send() mechanism works by injecting a value into the current yield expression — but if the generator has never run, there is no current yield expression. Sending a non-None value into that void is an error.

def my_gen():
    value = (yield "ready")
    yield value * 2

gen = my_gen()

# This raises TypeError — generator hasn't started yet
# gen.send(10)   # TypeError: can't send non-None value to a just-started generator

# Correct approach: prime first
first = next(gen)   # advances to first yield, returns "ready"
print(first)        # "ready"

result = gen.send(10)  # injects 10, generator yields 20
print(result)           # 20

Priming means advancing the generator to its first yield so that there is a suspended yield expression ready to receive input. The two standard ways to prime are next(gen) and gen.send(None). They are precisely equivalent: as confirmed by the CPython source and PEP 342, __next__() is implemented as send(None). Sending None is allowed on a fresh generator because None is the defined neutral value — it becomes the value of the yield expression, which is fine as long as your generator checks for it (or you use next() which implies the same thing).

What happens when you .send() into an already-exhausted generator?

The article has described what happens when a .send() call reaches the end of a generator: StopIteration is raised and the generator is closed. But readers often run into a different, subtler problem — calling .send() again on a generator that is already in the GEN_CLOSED state. The error is the same exception class but a different situation entirely:

def one_shot():
    yield (yield "first")

gen = one_shot()
next(gen)              # prime → yields "first", suspends at outer yield
gen.send("second")     # injects "second" into inner yield; outer yield emits "second"
                       # returns "second" — generator is still alive, suspended at outer yield

try:
    gen.send("third")  # injects "third" into outer yield; generator returns (no more yields)
except StopIteration:
    print("Generator exhausted")

gen.send("fourth")     # StopIteration raised immediately — generator already closed
                       # NOT from running out of yields — the frame is gone

Both the third and fourth calls raise StopIteration, but they mean different things. The third call — gen.send("third") — is the normal end-of-iteration signal: the generator ran out of yield expressions and returned. Note that the second call, gen.send("second"), does not raise StopIteration — it returns "second" and leaves the generator still suspended, because the nested yield (yield "first") has two yield points, not one. The fourth call raises StopIteration immediately because the generator is already in the GEN_CLOSED state — there is no frame left to resume. A well-written driver loop always catches StopIteration on the call that exhausts the generator and stops there — if you see it immediately on what feels like the wrong call, use inspect.getgeneratorstate() to confirm the generator was already closed before you called.

next() vs .send() vs .send(None)

These three are closely related but not identical in intent, even when they produce the same mechanical outcome.

From CPython's perspective, next(gen) and gen.send(None) are the same operation. The distinction is one of intent and readability. Use next() when you are treating the generator as a plain iterator and do not care about two-way communication. Use .send(None) when you are explicitly driving a coroutine-style generator and want to be clear that you are choosing not to send a value this cycle. Use .send(value) when you have actual data to inject.

The Other Two: .throw() and .close()

PEP 342 added three methods to generators, not one. .send() gets most of the attention, but .throw() and .close() complete the picture — and understanding them clarifies what .send() is actually doing at the frame level.

.throw() — injecting an exception at the yield point

gen.throw(exc) resumes the generator at the currently suspended yield expression, but instead of supplying a value, it raises the specified exception there. Pass an exception instance directly — the older three-argument form gen.throw(ExcType, value, traceback) is deprecated since Python 3.12 (see Python 3.12 deprecations) and will be removed in a future version. The generator can catch the thrown exception with a normal try/except block and continue running, or let it propagate — in which case the exception bubbles out to the caller of .throw().

def resilient():
    while True:
        try:
            value = (yield "waiting")
            print(f"Got: {value}")
        except ValueError as e:
            print(f"Caught inside generator: {e}")
            # generator continues — does not stop

gen = resilient()
next(gen)                        # prime

gen.send("hello")                # Got: hello
gen.throw(ValueError("bad input"))  # Caught inside generator: bad input
gen.send("back to normal")       # Got: back to normal

The generator catches ValueError internally, handles it, loops back to the yield, and resumes normally. If the generator does not catch the thrown exception, the exception propagates out to the caller and the generator is exhausted. This is the mechanism that asyncio uses internally to cancel tasks — it throws CancelledError into a coroutine's suspended yield point.

.close() — shutting a generator down cleanly

gen.close() throws GeneratorExit into the generator at the current yield point. This gives the generator a chance to run any finally blocks and release resources before stopping. If the generator catches GeneratorExit and then yields again, Python raises RuntimeError — a generator that catches GeneratorExit must either return or re-raise it.

def with_cleanup():
    try:
        while True:
            value = (yield "running")
            print(f"Processing: {value}")
    except GeneratorExit:
        print("Generator is shutting down — cleaning up")
        # return here (or just fall off the end) — do NOT yield again

gen = with_cleanup()
next(gen)
gen.send("first")
gen.close()   # prints: Generator is shutting down — cleaning up
# gen is now exhausted — any further .send() raises StopIteration

# Python 3.13+ only
def string_collector():
    """Collects strings; returns CSV summary on close()."""
    items = []
    try:
        while True:
            s = (yield)
            if isinstance(s, str):
                items.append(s)
    except GeneratorExit:
        return ", ".join(items)   # returned by close() in Python 3.13+

gen = string_collector()
next(gen)           # prime
gen.send("alpha")
gen.send("beta")
gen.send("gamma")
summary = gen.close()   # Python 3.13+: returns "alpha, beta, gamma"
print(summary)          # alpha, beta, gamma

# Python 3.12 and earlier: gen.close() always returns None regardless

The send/yield Handshake: A Visual

The interaction between caller and generator through .send() is a back-and-forth handshake. Each party is suspended while the other runs. Step through the interaction below — each click advances one operation and shows exactly what value moves in which direction.

Real Patterns: Accumulators, State Machines, Pipelines

The value of .send() becomes concrete when you look at patterns where two-way communication simplifies otherwise awkward code.

Running Accumulator

A generator that maintains a running total is a classic illustration. Without .send(), you would need a class with mutable state or a closure with a nonlocal variable. With .send(), the generator's own frame is the state container:

def accumulator():
    total = 0
    while True:
        value = (yield total)  # emit current total; receive next addend
        if value is None:
            break
        total += value

acc = accumulator()
next(acc)          # prime: advances to first yield, emits 0

print(acc.send(5))   # total = 5,  emits 5
print(acc.send(10))  # total = 15, emits 15
print(acc.send(3))   # total = 18, emits 18

Each call to .send() adds a number to the running total and immediately returns the updated total. The generator carries the state between calls without any external variable. This is the pattern that PEP 342 used in its own accumulator example, cited in the Python documentation.

1  def accumulator():
2      total = 0
3      while True:
4          value = (yield total)
5          total += value
6  
7  acc = accumulator()
8  acc.send(5)   # <-- called without priming first

Resettable State Machine

State machines are another natural fit. The generator's local variables are the machine's state; .send() is the event input; the yielded value is the output or the new state label:

def traffic_light():
    states = {"red": "green", "green": "yellow", "yellow": "red"}
    current = "red"
    while True:
        override = (yield current)
        if override and override in states:
            current = override          # forced transition
        else:
            current = states[current]   # automatic cycle

light = traffic_light()
print(next(light))           # "red"   (auto-advance)
print(light.send(None))      # "green" (auto-advance)
print(light.send("red"))     # "red"   (forced override)
print(light.send(None))      # "green" (auto-advance from red)

Processing Pipeline

PEP 342 specifically motivated .send() with pipeline and consumer patterns. Multiple coroutine-style generators can be chained so that each one receives data from upstream and passes processed results downstream. The author notes show a thumbnail pipeline where image frames are sent into a generator that pages them, all using (yield) as the intake point:

def printer():
    """A simple sink: receives values and prints them."""
    while True:
        item = (yield)
        print(f"Processed: {item}")

def uppercaser(downstream):
    """Transforms input and forwards to downstream consumer."""
    while True:
        item = (yield)
        downstream.send(item.upper())

# Wire up the pipeline
sink = printer()
next(sink)

pipe = uppercaser(sink)
next(pipe)

pipe.send("hello")    # prints: Processed: HELLO
pipe.send("world")    # prints: Processed: WORLD

Each stage in the pipeline uses (yield) with no emitted value — it only receives. The yield expression here evaluates to whatever was sent in; nothing is emitted outward (the caller's .send() would return None). This is a valid and common pattern for pure consumer generators.

The Auto-Prime Decorator

Any generator designed to receive values with .send() must be primed before use. When you have many such generators in a codebase, the priming call scattered at every construction site is noise. PEP 342 itself demonstrates a @consumer decorator that handles priming automatically:

import functools

def consumer(func):
    """Decorator that auto-primes a generator on construction."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        gen = func(*args, **kwargs)
        next(gen)   # advance to the first yield
        return gen
    return wrapper

@consumer
def logger(prefix):
    while True:
        message = (yield)
        print(f"[{prefix}] {message}")

# No manual priming needed — the decorator handles it
log = logger("INFO")
log.send("Server started")   # [INFO] Server started
log.send("Request received") # [INFO] Request received

The decorator replaces the generator function with a wrapper that calls next() immediately after construction and returns the already-primed generator. Callers see a clean API: construct, then send. One caution applies: only use this decorator on generators that are genuinely designed to receive input from the first iteration. If the generator yields a meaningful value at the first yield — one the caller is supposed to see — the decorator silently discards it.

yield from and .send() Delegation

PEP 380 (Python 3.3) introduced yield from, which delegates to a subgenerator. A key part of that delegation is that .send() calls on the outer generator are automatically forwarded to the inner one. You do not need to manually wire them:

def inner():
    x = (yield "inner waiting")
    print(f"Inner received: {x}")
    y = (yield "inner waiting again")
    print(f"Inner received: {y}")

def outer():
    print("Outer: delegating to inner")
    yield from inner()
    print("Outer: inner exhausted, continuing")

gen = outer()
print(next(gen))          # Outer: delegating to inner
                          # inner waiting
print(gen.send("alpha"))  # Inner received: alpha
                          # inner waiting again
try:
    gen.send("beta")      # Inner received: beta
                          # Outer: inner exhausted, continuing
except StopIteration:
    pass

The gen.send("alpha") call on the outer generator is transparently forwarded by yield from directly into the inner generator's suspended yield expression. The outer generator never sees the values — it simply acts as a transparent conduit. The same forwarding applies to .throw() and .close(). This delegation mechanism is the foundation of Python's asyncio coroutine chain: at the bytecode level, await is implemented using YIELD_VALUE and a dedicated GET_AWAITABLE opcode (not YIELD_FROM — PEP 492 intentionally uses a distinct opcode to restrict what await accepts), but the protocol of forwarding .send() calls down through a chain of awaitables to the event loop mirrors the same delegation pattern that yield from established.

What a Generator's return Value Actually Does

The article has shown that when a generator runs out of yield expressions, StopIteration is raised. What it has not yet covered is that a return value statement inside a generator sets StopIteration.value — and that yield from captures this value and makes it available to the outer generator as the result of the entire delegation.

This is the missing link between .send(), subgenerator delegation, and bidirectional communication across multiple generator layers:

def inner_worker():
    total = 0
    while True:
        value = (yield)
        if value is None:
            return total    # return value becomes StopIteration.value
        total += value

def outer():
    # yield from captures the return value of inner_worker
    # when inner_worker returns, result gets that value
    result = yield from inner_worker()
    yield f"Final total: {result}"

gen = outer()
next(gen)          # prime — advances into inner_worker's first yield

gen.send(10)
gen.send(25)
gen.send(7)

# Sending None signals inner_worker to return its total
# yield from captures the return value and assigns it to `result`
# outer then hits its own yield
print(gen.send(None))  # Final total: 42

Three things happen here that are easy to miss. First, return total inside a generator does not immediately propagate as an unhandled exception — it sets StopIteration.value to total and exits the generator normally. Second, yield from specifically intercepts that StopIteration, extracts its .value, and makes it the result of the yield from expression on the left-hand side — so result = yield from inner_worker() gives outer the computed total without any extra plumbing. Third, if you were driving this without yield from — calling .send() on the inner generator directly — you would need to catch StopIteration yourself and read e.value to retrieve the return value:

# Driving inner_worker manually — no yield from
worker = inner_worker()
next(worker)

worker.send(10)
worker.send(25)

try:
    worker.send(None)   # triggers return inside generator
except StopIteration as e:
    print(e.value)      # 35 — the return value is on StopIteration.value

This pattern matters in practice whenever you write generator-based protocols or implement a custom scheduler. The return value of a subgenerator is how it communicates its final result back to its caller — and yield from is what makes that communication automatic rather than requiring manual exception handling at every delegation boundary.

CPython Internals: What Actually Happens When You Call .send()

The previous sections described the behavior of .send() from the outside. This section goes to the machine level. None of what follows is required to use generators correctly, but it resolves questions that every experienced Python developer eventually runs into — why certain errors have the wording they do, what changed across Python versions, and what those undocumented attributes on the generator object are actually tracking.

RETURN_GENERATOR: How a Generator Object Is Created (Python 3.11+)

When you call a generator function, none of its body runs. What actually happens is that CPython's compiler emits RETURN_GENERATOR as the very first opcode of every generator function's bytecode. When that opcode executes, the interpreter allocates a PyGenObject, copies the current interpreter frame into it as an embedded _PyInterpreterFrame, immediately returns that generator object to the caller, and discards the outer frame. The body of the function — every statement you wrote — sits in the bytecode immediately after RETURN_GENERATOR, and none of it runs until the first next() or .send(None).

You can observe this directly:

import dis

def my_gen():
    x = (yield 1)
    yield x + 1

dis.dis(my_gen)
# Python 3.11+:
#   0  RETURN_GENERATOR       ← creates the generator object and returns it
#   2  RESUME          0
#   4  LOAD_CONST      1 (1)
#   6  YIELD_VALUE     0      ← suspends; sent value becomes x
#   8  RESUME          1
#  10  LOAD_FAST       0 (x)
#  12  LOAD_CONST      1 (1)
#  14  BINARY_OP       0 (+)
#  18  YIELD_VALUE     0
#  20  RESUME          1
#  22  LOAD_CONST      0 (None)
#  24  RETURN_VALUE

RETURN_GENERATOR was added in Python 3.11 (replacing the older GEN_START opcode from Python 3.10 and the even older mechanism before that). The shift matters for one subtle reason: because the generator's frame is now an embedded _PyInterpreterFrame inside the PyGenObject struct rather than a heap-allocated PyFrameObject, Python 3.11 significantly reduced the allocation cost of creating a generator. Old-style PyFrameObject heap objects are now only created on demand — when debuggers or introspection functions such as sys._getframe() request them — rather than for every generator creation.

The SEND Opcode: How yield from and await Delegate .send() at the Bytecode Level

Before Python 3.11, yield from compiled to a YIELD_FROM opcode. In Python 3.11 that opcode was removed and replaced with SEND. The SEND opcode is defined as:

STACK[-1] = STACK[-2].send(STACK[-1]) — if the call raises StopIteration, pop the top value, push StopIteration.value, and advance the instruction pointer past the delegation block.

SEND is used for both yield from and await. This means every await expression in an async def function is, at the bytecode level, a SEND that forwards the event loop's injected values down through a chain of awaitable objects. The distinction between await and yield from is enforced at the type level by a separate opcode (GET_AWAITABLE) that restricts what objects can be awaited, not at the SEND level — both compile to the same delegation primitive.

gi_yieldfrom: Seeing the Active Subgenerator

When a generator is suspended inside a yield from delegation, it exposes the subgenerator it is currently waiting on through the gi_yieldfrom attribute. This attribute was added in Python 3.5 (issue #24450, contributed by Benno Leslie and Yury Selivanov). It is None whenever the generator is not currently delegating to another generator. Its coroutine equivalent is cr_await.

def inner():
    yield "inner waiting"

def outer():
    yield from inner()

gen = outer()
next(gen)   # prime — outer is now suspended inside yield from

print(gen.gi_yieldfrom)   # 
# gi_yieldfrom is the live inner() generator object
# You can call .send() or .throw() on it directly if needed for debugging

This attribute is practically useful when debugging a suspended generator chain: if .send() behaves unexpectedly, inspecting gi_yieldfrom tells you exactly which subgenerator is currently holding control, without disrupting execution.

gi_suspended: The Cheaper State Check (Python 3.11+)

Python 3.11 added a gi_suspended attribute directly to generator objects. It is a C-level integer field — 1 if the generator is currently suspended at a yield expression, 0 otherwise. Unlike inspect.getgeneratorstate(), reading gi_suspended requires no Python function call and no import. The inspect module's own implementation of getgeneratorstate() now uses gi_suspended internally as its fast path.

def my_gen():
    yield 1

gen = my_gen()
print(gen.gi_suspended)   # 0 — not yet suspended (GEN_CREATED)

next(gen)
print(gen.gi_suspended)   # 1 — suspended at the yield

try:
    next(gen)
except StopIteration:
    pass
print(gen.gi_suspended)   # 0 — closed (GEN_CLOSED)

In tight scheduler loops that check generator state frequently, reading gen.gi_suspended directly is measurably faster than calling inspect.getgeneratorstate(gen). The coroutine equivalent is cr_suspended (also added in Python 3.11); async generators gained ag_suspended in Python 3.12.

Each PyGenObject in CPython carries its own gi_exc_state field — a private exception state stack independent of the calling thread's exception state. When the interpreter enters a generator's frame (on any .send() call), it swaps the thread's active exception state for the generator's saved one. When the generator suspends, the generator's exception state is saved back into gi_exc_state and the caller's exception state is restored.

This swap behavior was introduced in Python 3.7 (commit ae3087c, "Move exc state to generator", fixing bpo-25612). Before 3.7, exception state lived in the frame object, which caused obscure bugs where an active exception caught inside a generator could be visible in the caller's sys.exc_info() after the generator yielded. The fix — moving gi_exc_state to the generator object itself — is why the following code behaves correctly today but would have produced surprising results in Python 3.6 and earlier:

import sys

def gen_with_caught_exception():
    try:
        raise ValueError("inside generator")
    except ValueError:
        yield "caught it"   # yields while an exception is active inside gen
    yield "done"

g = gen_with_caught_exception()
print(next(g))               # "caught it"
print(sys.exc_info())        # (None, None, None) — caller's exception state is clean
                             # In Python 3.6, this would have shown the ValueError

Why the .throw() Method Is Named "throw" and Not "raise"

The name throw was chosen deliberately and specifically because raise is a Python keyword and cannot be used as a method name. The name first appeared in PEP 288 (Raymond Hettinger, 2002), which proposed generator exception injection before PEP 342 existed. PEP 288 noted that throw was also already associated with exception injection in other languages, that it was suggestive of placing the exception in a different location, and that alternatives considered — resolve(), signal(), genraise(), raiseinto(), flush() — were all judged inferior. PEP 342 adopted the name from PEP 288 without change.

yield from with Plain Iterables: When .send() Degrades to next()

yield from works on any iterable, not only on generators. When given a plain iterable such as a list or range, it calls iter() on it to produce a plain iterator. That plain iterator has no .send() method. The PEP 380 delegation specification handles this explicitly: when the delegating generator receives a .send(value) call and the subiterator is a plain iterator, if value is None the delegation falls back to calling next() on the subiterator. If value is non-None, Python calls subiterator.send(value), which raises AttributeError on a plain iterator — the caller of the delegating generator sees that AttributeError propagated out. The practical consequence: a generator using yield from some_list can be primed and advanced with next() safely, but calling .send("data") on it will raise AttributeError because the list iterator has no send channel.

Where .send() Fits Now That async/await Exists

Python 3.5 introduced native coroutines via PEP 492, with the async def and await syntax. One of PEP 492's explicit motivations was the confusion between generator-based coroutines and plain generators: they shared syntax, which made it difficult to tell at a glance whether a function was intended to be driven with next() or as a coroutine. Native coroutines removed that ambiguity by creating a distinct type with its own syntax.

PEP 492 (Yury Selivanov) noted that distinguishing coroutines from regular generators was a persistent source of confusion, particularly for developers newer to Python, given that both shared the same syntax.

As Luciano Ramalho explains in Fluent Python (O'Reilly), the .send() infrastructure arrived with PEP 342 in Python 2.5, which was when yield became a proper expression and generators gained the ability to function as coroutines. Native async/await coroutines build on the same underlying mechanism — coroutine objects still expose .send(), .throw(), and .close() — but the event loop calls those methods internally, and application code never calls .send() directly.

This means .send() on generators remains relevant in several specific situations today:

It is appropriate when you are writing a stateful generator that needs two-way communication but does not need to participate in an async event loop. The accumulator and state machine patterns above are examples where async/await would be unnecessary overhead. It is also appropriate when you are working at a low level with coroutine objects — writing a custom event loop, implementing a trampoline scheduler, or building a testing harness that drives coroutines directly. And it appears in the implementation of yield from (PEP 380, Python 3.3), which internally forwards .send() calls down to subgenerators through the delegation chain.

For ordinary asynchronous I/O and task coordination, async/await is the right tool. For synchronous stateful computation with bidirectional communication, .send() on a plain generator is still clean and precise.

Inspecting Generator State

When a .send() call misbehaves — wrong value comes back, unexpected TypeError, premature StopIteration — the first question is usually: where is this generator right now? Python exposes that through the inspect module and a few attributes on the generator object itself.

import inspect

def my_gen():
    yield 1
    yield 2

gen = my_gen()

print(inspect.getgeneratorstate(gen))  # GEN_CREATED  — never started

next(gen)
print(inspect.getgeneratorstate(gen))  # GEN_SUSPENDED — at a yield

# exhaust it
list(gen)
print(inspect.getgeneratorstate(gen))  # GEN_CLOSED — no more yields

gen2 = my_gen()
gen2.close()
print(inspect.getgeneratorstate(gen2)) # GEN_CLOSED — explicitly closed

The four states are GEN_CREATED (constructed, never advanced — this is why .send(non_None) fails here), GEN_RUNNING (currently executing, only visible from inside the generator itself), GEN_SUSPENDED (paused at a yield, ready to receive .send()), and GEN_CLOSED (exhausted or closed).

The generator's current local variables are accessible via gen.gi_frame.f_locals when the state is GEN_SUSPENDED. Once the generator is closed, gi_frame is None. This is useful when debugging a long-running stateful generator to verify what the accumulated state looks like without disrupting execution:

def accumulator():
    total = 0
    while True:
        value = (yield total)
        if value is None:
            break
        total += value

acc = accumulator()
next(acc)
acc.send(10)
acc.send(25)

# Peek at internal state without consuming the generator
print(acc.gi_frame.f_locals)  # {'total': 35, 'value': 25}

Python Notes to Remember

The generator protocol in Python has always been richer than the basic for loop version of it suggests. .send() is the part that turns a generator from a one-directional sequence producer into something closer to a function that can be paused, handed a value, and then continued — a pattern that underpins everything from simple stateful counters to the coroutine machinery that powers Python's entire async ecosystem.

Frequently Asked Questions

def doubler():
    while True:
        x = (yield)
        if x is None:
            break
        yield x * 2

gen = doubler()
next(gen)  # prime

inputs = [3, 7, 11]
for value in inputs:
    result = gen.send(value)   # send input in
    print(result)              # 6, 14, 22
    next(gen)                  # advance past the second yield before sending again

import pytest

def accumulator():
    total = 0
    while True:
        value = (yield total)
        if value is None:
            return total
        total += value

def test_accumulator_basic():
    gen = accumulator()
    assert next(gen) == 0        # primed; yields initial total
    assert gen.send(10) == 10    # total is now 10
    assert gen.send(25) == 35    # total is now 35
    assert gen.send(5)  == 40    # total is now 40

def test_accumulator_termination():
    gen = accumulator()
    next(gen)
    gen.send(7)
    with pytest.raises(StopIteration) as exc_info:
        gen.send(None)           # signals the generator to return
    assert exc_info.value.value == 7   # StopIteration.value holds the return value