{"id":1202,"date":"2020-11-18T01:48:38","date_gmt":"2020-11-18T01:48:38","guid":{"rendered":"https:\/\/www.pythontutorial.net\/?page_id=1202"},"modified":"2025-03-27T15:04:06","modified_gmt":"2025-03-27T15:04:06","slug":"python-generators","status":"publish","type":"page","link":"https:\/\/www.pythontutorial.net\/advanced-python\/python-generators\/","title":{"rendered":"Python Generators"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you’ll learn about Python generators and how to use generators to create iterators<\/p>\n\n\n\n

Introduction to Python generators #<\/a><\/h2>\n\n\n\n

Typically, Python executes a regular function<\/a> from top to bottom based on the run-to-completion model.<\/p>\n\n\n\n

It means that Python cannot pause a regular function midway and then resumes the function after that. For example:<\/p>\n\n\n

def<\/span> greeting<\/span>()<\/span>:<\/span>\n    print('Hi!'<\/span>)\n    print('How are you?'<\/span>)\n    print('Are you there?'<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
When Python executes the greeting()<\/code> function, it executes the code line by line from top to bottom.<\/p>\n\n\n\n
Also, Python cannot pause the function at the following line:<\/p>\n\n\n
print('How are you?'<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
… and jumps to another code and resumes the execution from that line.<\/p>\n\n\n\n
To pause a function midway and resume from where the function was paused, you use the yield<\/code> statement.<\/p>\n\n\n\n
When a function contains at least one yield<\/code> statement, it’s a generator function<\/strong>.<\/p>\n\n\n\n
By definition, a generator is a function that contains at least one yield statement.<\/p>\n\n\n\n
When you call a generator function, it returns a new generator object. However, it doesn’t start the function.<\/p>\n\n\n\n
A simple Python generator example #<\/a><\/h2>\n\n\n\n
See the following example:<\/p>\n\n\n
def<\/span> greeting<\/span>()<\/span>:<\/span>\n    print('Hi!'<\/span>)\n    yield<\/span> 1<\/span>\n    print('How are you?'<\/span>)\n    yield<\/span> 2<\/span>\n    print('Are you there?'<\/span>)\n    yield<\/span> 3<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Since the greeting()<\/code> function contains the yield<\/code> statements, it’s a generator function.<\/p>\n\n\n\n
The yield<\/code> statement is like a return<\/code> statement in a function. However, there’s a big difference.<\/p>\n\n\n\n
When Python encounters the yield<\/code> statement, it returns the value specified in the yield<\/code>. In addition, it pauses the execution of the function.<\/p>\n\n\n\n
If you “call” the same function again, Python will resume from where the previous yield<\/code> statement was encountered.<\/p>\n\n\n\n
When you call a generator function, it returns a generator object. For example:<\/p>\n\n\n
messenger = greeting()<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
To actually execute the body of the greeting()<\/code> function, you need to use the next()<\/code> built-in function:<\/p>\n\n\n
result = next(messenger)\nprint(result)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
When you the greeting()<\/code> function executes, it shows the first message and returns 1:<\/p>\n\n\n
Hi!\n1<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Also, it’s paused right at the first yield<\/code> statement. If you “call” the greeting()<\/code> function again, it’ll resume the execution from the last yield<\/code> statement:<\/p>\n\n\n
result = next(messenger)\nprint(result)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
How are you?\n2<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
And you can call it again:<\/p>\n\n\n
result = next(messenger)\nprint(result) <\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Are you there?\n3<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
next(messenger)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
StopIteration      <\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Here’s the whole program:<\/p>\n\n\n
def greeting():\n    print<\/span>('Hi!'<\/span>)\n    yield<\/span> 1<\/span>\n    print<\/span>('How are you?'<\/span>)\n    yield<\/span> 2<\/span>\n    print<\/span>('Are you there?'<\/span>)\n    yield<\/span> 3<\/span>\n\nmessenger = greeting()\n\nresult = next(messenger)\nprint<\/span>(result)\n\nresult = next(messenger)\nprint<\/span>(result)\n\nresult = next(messenger)\nprint<\/span>(result)\n\nprint<\/span>(result)<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
Hi!\n1\nHow are you?\n2\nAre you there?\n3\n3\n<\/code><\/span><\/pre>\n\n\n
Using Python generators to create iterators #<\/a><\/h2>\n\n\n\n
The following example defines an iterator that returns a square number of an integer.<\/p>\n\n\n
class<\/span> Squares<\/span>:<\/span>\n    def<\/span> __init__<\/span>(self, length)<\/span>:<\/span>\n        self.length = length\n        self.current = 0<\/span>\n\n    def<\/span> __iter__<\/span>(self)<\/span>:<\/span>\n        return<\/span> self\n\n    def<\/span> __next__<\/span>(self)<\/span>:<\/span>\n        result = self.current ** 2<\/span>\n\n        self.current += 1<\/span>\n\n        if<\/span> self.current > self.length:\n            raise<\/span> StopIteration\n\n        return<\/span> result<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
And you can use the Squares<\/code> iterator to generate the square numbers of the first 5 integers from 0 to 5:<\/p>\n\n\n
length = 5<\/span>\nsquare = Squares(length)\nfor<\/span> s in<\/span> square:\n    print(s)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
This code works as we expected. But it has one issue that there’s a lot of boilerplate.<\/p>\n\n\n\n
And as you might guess, you use a generator function to build that iterator.<\/p>\n\n\n\n
The following rewrites the Squares<\/code> iterator as a generator function:<\/p>\n\n\n
def<\/span> squares<\/span>(length)<\/span>:<\/span>\n    for<\/span> n in<\/span> range(length):\n        yield<\/span> n ** 2<\/span><\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
The new code is much shorter and more expressive. The usage of the squares<\/code> generator function is similar to the iterator above:<\/p>\n\n\n
length = 5<\/span>\nsquare = squares(length)\nfor<\/span> s in<\/span> square:\n    print(s)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Summary #<\/a><\/h2>\n\n\n\n
    \n
  • Python generators are functions that contain at least one yield statement.<\/li>\n\n\n\n
  • A generator function returns a generator object.<\/li>\n\n\n\n
  • A generator object is an iterator. Therefore, it becomes exhausted once there’s no remaining item to return.<\/li>\n<\/ul>\n
    \n\t
    \n\t\t
    Was this tutorial helpful ?<\/div>\n\t\t
    \n\t\t\t\n\t\t\t\t\n\t\t\t\t\t<\/path>\n\t\t\t\t<\/svg>\n\t\t\t\t Yes <\/span>\n\t\t\t<\/button>\n\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t<\/path>\n\t\t\t\t<\/svg>\n\t\t\t\t No <\/span>\n\t\t\t<\/button>\n\t\t<\/div>\n\t<\/header>\n\n\t
    \n\t\t
    \n\t\t\t
    <\/div>\n\t\t\t
However, if you execute the generator once more time, it’ll raise the StopIteration exception because it’s an iterator<\/a>:<\/p>\n\n\n
The messenger<\/code> is a generator object, which is also an iterator<\/a>.<\/p>\n\n\n\n
Generator objects (or generators) implement the iterator protocol<\/a>. In fact, generators are lazy iterators. Therefore, to execute a generator function, you call the next()<\/code> built-in function on it.<\/p>\n\n\n\n