This rule raises an issue when a for loop only yields each element of an iterable and could be replaced by a yield from statement.

Why is this an issue?

Introduced by PEP 380, the yield from statement delegates the iteration to another iterable.

def generator():
    yield from range(10)

Rewriting a for loop whose body is a single yield of the loop variable into yield from has several benefits:

• It states the intent directly: the generator delegates to another iterable instead of manually relaying its values.
• It removes a loop variable that serves no other purpose.
• It is faster, because the values are relayed by the interpreter instead of going through a Python-level loop.
• It reaches the sub-generator: send(), throw() and close() are routed into it instead of stopping at the outer generator. Only send() is silently swallowed by a manual loop, but none of the three reach the sub-generator.
• It makes the sub-generator’s return value available as the value of the yield from expression, where a manual loop discards it.

How to fix it

Replace the for loop with a yield from statement over the same iterable.

Code examples

Noncompliant code example

def read_events(source):
    for event in parse_events(source):  # Noncompliant: this loop only relays the parsed events
        yield event

Compliant solution

def read_events(source):
    yield from parse_events(source)

Pitfalls

yield from is not allowed in asynchronous generators. An async for loop that yields each element cannot be rewritten this way, and this rule does not raise an issue on such loops.

async def relay(async_iterable):
    async for value in async_iterable:
        yield value

The two forms are equivalent as long as the sub-iterable is only iterated over. They diverge once the caller drives the outer generator directly:

• send(value) is swallowed by a manual loop, which just resumes and yields the next element. yield from passes the value to the sub-generator.
• throw(exc) raises the exception in the outer generator, where a manual loop lets it propagate to the caller. yield from offers it to the sub-generator first, giving it a chance to handle it.
• close() ends the outer generator in both forms. yield from also closes the sub-generator.

The sub-generator’s return value also becomes the value of the yield from expression instead of being discarded. Check how the sub-iterable is consumed before rewriting a loop that delegates to a generator.

Resources

Documentation

• Python Documentation - Yield expressions
• Python Documentation - The yield statement

Standards

• PEP 380 - Syntax for Delegating to a Subgenerator