The Python Yield Keyword: A Guide

How to Use the Python Yield Keyword

Generators aren’t the most intuitive concept in Python. To make matters worse, they use a special keyword called “yield,” even though generators are themselves functions. What is the yield keyword? How does it compare to a return statement?

Those are good questions. In this guide, we talk about what the yield statement is and how you can use it in your code. We walk through an example of the yield keyword in action. Let’s get started!

We recommend reading our articles on Python iterators and generators before continuing. This gives you some useful context that you can use to further your understanding of the yield keyword.

Back to Basics: Iterators and Generators

Lists are described as iterable objects. This is because you can view their contents using a “for” loop. Every time the loop executes, an item in the list is accessed by Python. Dictionaries, tuples, and strings are also iterable objects.

A function that accesses an item from an iterable object is called an iterator. Let’s create a list and iterate over it using a for loop:

peppers = ["Scotch Bonnet", "Piri Piri", "Cayenne"]

for p in peppers:
	print(p)
for p in peppers:
	print(p)

This code prints out all of the peppers in the “peppers” list to the console:

Scotch Bonnet
Piri Piri
Cayenne
Scotch Bonnet
Piri Piri
Cayenne

We use our iterator as many times as we want. In the last example, we iterated over the “peppers” object twice.

Python generators are like an iterator used to repeat an object. There is one big difference: You can only iterate over a generator once. Whereas we can iterate over “peppers” as many times as we want, a generator is only accessed once.

Let’s define a generator for our list of peppers:

def print_peppers(peppers):
	for p in peppers:
		yield p

peppers = ["Scotch Bonnet", "Piri Piri", "Cayenne"]
pepper_generator = print_peppers(peppers)

for p in pepper_generator:
	print(p)

We define a function called print_peppers(). This is our generator function. It accepts one argument: a list of peppers that we want to print to the console.

In our main program, we call the print_peppers() function and assign it to the variable pepper_generator. Next, we iterate over the generator using a “for” loop. Our for loop calls the generator object and iterates over it.

Let’s run our code:

Scotch Bonnet
Piri Piri
Cayenne

The output is the same as our first example. The difference is we can only iterate over our list once. Let’s try to iterate over our generator again:

...
for p in pepper_generator:
	print(p)
for p in pepper_generator:
	print(p)

Our code returns:

Scotch Bonnet
Piri Piri
Cayenne

We’ve iterated over our generator once. We cannot do it again. That’s why our second for loop does not return any values.

The Python Yield Keyword

Notice the word “yield” in the last example. Here’s a reminder:

def print_peppers(peppers):
	for p in peppers:
		yield p

The “yield” keyword appears inside our function. It returns a value in a generator function. It’s similar to the “return” keyword.

Use yield when you want to create a generator over which you can iterate. In our last example, we use yield to create a generator for our list of peppers.

Any function that contains yield will return a generator. We see this by checking the type of the pepper_generator variable using the type() method:

<class 'generator'>

This tells us that pepper_generator, which is assigned the print_peppers function, is a generator.

Conclusion

The yield keyword returns a value inside a generator. A generator is a special type of iterator whose values can only be iterated over once. The yield keyword is similar to a return statement except return statements cannot be used in generators.

Now you’re ready to use the yield keyword like a Pythonista!