Python Iterators

You've used for loops on lists, strings and dictionaries since the for loop lesson. But how does Python actually step through them? The answer is Python iterators: small objects that remember where you are and give you the next value when you ask. In this lesson, you'll learn the difference between an iterable and an iterator, use iter() and next() by hand, see what a for loop does under the hood, and build your own iterator class.

What is an iterable in Python?

An iterable is any object you can loop over: lists, tuples, strings, sets, dictionaries, range() objects and files. Technically, an iterable is an object that can give you an iterator when you pass it to the built-in iter() function.

An iterable holds (or can produce) the data, but it doesn't keep track of a position. You can loop over the same list as many times as you like.

What is an iterator in Python?

An iterator is an object that produces values one at a time and remembers its position. You ask it for the next value with the built-in next() function. Every iterator has two special methods:

• __iter__() returns the iterator itself.
• __next__() returns the next value, or raises StopIteration when there are no values left.

How do you use iter() and next()?

Call iter() on an iterable to get an iterator, then call next() to pull out values one by one:

playlist = ["Intro", "Sunrise", "Night Drive"]

player = iter(playlist)

print(next(player))
print(next(player))
print(next(player))

Intro
Sunrise
Night Drive

Each call to next() moves the iterator one step forward. The list itself never changes; only the iterator's position does.

What is StopIteration?

When an iterator runs out of values, next() raises a StopIteration exception. It's Python's way of saying "that's everything":

player = iter(["Intro", "Sunrise"])

print(next(player))
print(next(player))
print(next(player))

Intro
Sunrise
StopIteration

If you'd rather not get an error, give next() a second argument. It's returned instead of raising StopIteration:

player = iter(["Intro"])

print(next(player, "End of playlist"))
print(next(player, "End of playlist"))

Intro
End of playlist

How does a for loop work under the hood?

A for loop is really a friendly shortcut for iter(), next() and StopIteration. This loop:

for song in ["Intro", "Sunrise", "Night Drive"]:
    print("Now playing:", song)

Now playing: Intro
Now playing: Sunrise
Now playing: Night Drive

does the same thing as this longer version, which uses a while loop and try/except:

player = iter(["Intro", "Sunrise", "Night Drive"])

while True:
    try:
        song = next(player)
    except StopIteration:
        break
    print("Now playing:", song)

Now playing: Intro
Now playing: Sunrise
Now playing: Night Drive

Python calls iter() once at the start, calls next() before each pass through the loop body, and quietly stops when StopIteration appears. That's why a for loop works on any iterable: lists, strings, files, and even objects you write yourself.

An iterator only goes forward, once

Because an iterator remembers its position, a second loop over the same iterator finds nothing left:

scores = iter([88, 92, 75])

for score in scores:
    print(score)

print("Second loop:")
for score in scores:
    print(score)

88
92
75
Second loop:

A list, on the other hand, gives the loop a new iterator each time, so looping over a list twice works fine.

How do you create your own iterator class?

To make an iterator, write a class with the two magic methods __iter__() and __next__(). Here's a countdown for a rocket launch:

class Countdown:
    def __init__(self, start):
        self.current = start

    def __iter__(self):
        return self

    def __next__(self):
        if self.current < 1:
            raise StopIteration
        value = self.current
        self.current -= 1
        return value

for number in Countdown(3):
    print(number)
print("Liftoff!")

3
2
1
Liftoff!

Step by step:

• __init__() stores the starting position.
• __iter__() returns self, because the object is its own iterator.
• __next__() returns the current number and moves one step down. When it goes below 1, it raises StopIteration, which ends the loop.

Real-world example: a playlist with a "next song" button

This iterator class wraps a list of songs and loops back to the start when repeat is on, just like the repeat button in a music app:

class Playlist:
    def __init__(self, songs, repeat=False):
        self.songs = songs
        self.repeat = repeat
        self.position = 0

    def __iter__(self):
        return self

    def __next__(self):
        if self.position == len(self.songs):
            if not self.repeat:
                raise StopIteration
            self.position = 0
        song = self.songs[self.position]
        self.position += 1
        return song

player = Playlist(["Intro", "Sunrise"], repeat=True)

for tap in range(5):
    print("Next song:", next(player))

Next song: Intro
Next song: Sunrise
Next song: Intro
Next song: Sunrise
Next song: Intro

With repeat=True, the iterator never runs out, so we called next() a fixed number of times instead of using a for loop over it. A for song in player: loop would run forever.

Common mistakes

1. Calling next() on a list

songs = ["Intro", "Sunrise"]
print(next(songs))

TypeError: 'list' object is not an iterator

A list is iterable, not an iterator. Call iter(songs) first.

2. Expecting an iterator to restart

Once an iterator is used up, it stays empty. Create a new one with iter(), or keep your data in a list if you need to loop over it several times.

3. Forgetting to raise StopIteration

If __next__() never raises StopIteration, a for loop over the object never ends. Always include a clear stopping condition, unless the iterator is meant to be infinite and you control how many values you take.

4. Forgetting __iter__()

A class with only __next__() can't be used in a for loop. Python calls iter() first, so it needs __iter__() to return the iterator.

Practice exercise

class EvenNumbers:
    def __init__(self, limit):
        self.limit = limit
        self.current = 2

    def __iter__(self):
        return self

    def __next__(self):
        if self.current > self.limit:
            raise StopIteration
        value = self.current
        self.current += 2
        return value

for number in EvenNumbers(10):
    print(number, end=" ")

2 4 6 8 10

What's next?

Iterator classes work, but they take a lot of code. Next, learn the much shorter way to build iterators with yield in Python generators.