Python Iterators

Learning Objectives

By the end of this lesson, you will understand how Python's iteration system works and how objects can provide values one at a time.

What Is Iteration?

Iteration means going through a collection or sequence one item at a time.

You have already used iteration many times with for loops.

numbers = [10, 20, 30, 40]

for number in numbers:
    print(number)

10
20
30
40

The for loop retrieves each value from the collection until there are no more values.

Iterable vs Iterator

These two terms sound similar, but they are not exactly the same.

Iterable

An iterable is an object that can provide an iterator.

Common iterables include:

• Lists
• Tuples
• Strings
• Sets
• Dictionaries
• Files
• Ranges

numbers = [1, 2, 3]

name = "Python"

values = {10, 20, 30}

for item in numbers:
    print(item)

Iterator

An iterator is an object that produces values one at a time and remembers its current position.

The iter() Function

The built-in iter() function creates or retrieves an iterator from an iterable.

numbers = [10, 20, 30]

iterator = iter(numbers)

print(iterator)

Now iterator is an iterator over the list.

We can ask it for individual values using next().

The next() Function

The next() function retrieves the next available value from an iterator.

numbers = [10, 20, 30]

iterator = iter(numbers)

print(next(iterator))
print(next(iterator))
print(next(iterator))

10
20
30

Every time next() is called, the iterator moves forward.

How for Loops Work

A for loop hides much of the iterator machinery from you.

Conceptually, this:

numbers = [10, 20, 30]

for number in numbers:
    print(number)

behaves roughly like:

numbers = [10, 20, 30]

iterator = iter(numbers)

while True:

    try:
        number = next(iterator)
        print(number)

    except StopIteration:
        break

StopIteration

When an iterator has no more values, it signals that iteration is finished by raising StopIteration.

numbers = [1, 2]

iterator = iter(numbers)

print(next(iterator))
print(next(iterator))

print(next(iterator))

1
2
StopIteration

A normal for loop handles this automatically. You generally do not see the exception when using standard iteration.

Creating a Custom Iterator

One of the most important skills in this lesson is creating your own iterator.

A typical custom iterator implements:

• __iter__()
• __next__()

These methods define the iterator protocol.

__iter__()

The __iter__() method returns an iterator.

For an iterator object, __iter__() normally returns self.

class Counter:

    def __iter__(self):
        return self

Returning self means the object itself is the iterator.

__next__()

The __next__() method returns the next value.

When there are no more values, it must raise StopIteration.

class Counter:

    def __init__(self, maximum):
        self.current = 1
        self.maximum = maximum

    def __iter__(self):
        return self

    def __next__(self):

        if self.current <= self.maximum:
            value = self.current
            self.current += 1
            return value

        raise StopIteration

The current variable stores the iterator's current position.

Complete Iterator Class

Let's combine everything into a working iterator.

class Counter:

    def __init__(self, maximum):
        self.current = 1
        self.maximum = maximum

    def __iter__(self):
        return self

    def __next__(self):

        if self.current <= self.maximum:
            value = self.current
            self.current += 1
            return value

        raise StopIteration


counter = Counter(5)

for number in counter:
    print(number)

1
2
3
4
5

The for loop automatically calls iter() and repeatedly calls next() until StopIteration occurs.

Iterator State

An important characteristic of an iterator is that it remembers where it currently is.

numbers = [10, 20, 30]

iterator = iter(numbers)

print(next(iterator))
print(next(iterator))

print(next(iterator))

The iterator does not start from the beginning every time. It remembers its current position.

Iterators Are Usually One-Time Use

Once an iterator reaches the end, it normally stays exhausted.

numbers = [1, 2, 3]

iterator = iter(numbers)

for number in iterator:
    print(number)

print("Again:")

for number in iterator:
    print(number)

1
2
3
Again:

The second loop has nothing to process because the iterator has already been exhausted.

Converting Iterables into Iterators

Many Python objects are iterable but are not themselves iterators.

numbers = [10, 20, 30]

iterator = iter(numbers)

print(next(iterator))
print(next(iterator))

The list is the iterable, while the object returned by iter(numbers) is the iterator.

Checking with iter()

An object can be considered iterable when Python can obtain an iterator from it.

values = [1, 2, 3]

iterator = iter(values)

print(next(iterator))

Practical Examples

Example 1 — Countdown

class Countdown:

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

    def __iter__(self):
        return self

    def __next__(self):

        if self.current <= 0:
            raise StopIteration

        value = self.current
        self.current -= 1

        return value


for number in Countdown(5):
    print(number)

5
4
3
2
1

Example 2 — Even Numbers

class EvenNumbers:

    def __init__(self, maximum):
        self.current = 0
        self.maximum = maximum

    def __iter__(self):
        return self

    def __next__(self):

        self.current += 2

        if self.current <= self.maximum:
            return self.current

        raise StopIteration


for number in EvenNumbers(10):
    print(number)

2
4
6
8
10

Example 3 — Processing Records

Iterators can be useful when processing records one at a time instead of manually handling the entire sequence.

records = [
    "Order 1001",
    "Order 1002",
    "Order 1003"
]

orders = iter(records)

print(next(orders))
print(next(orders))

This concept becomes especially useful when working with large datasets, files, streams, and other potentially large sources of data.

Common Mistakes

Practice Exercises

Mini Challenge — Custom Number Iterator

Build a reusable iterator called NumberRange.

It should produce numbers from a starting value to an ending value.

class NumberRange:

    def __init__(self, start, end):
        self.current = start
        self.end = end

    def __iter__(self):
        return self

    def __next__(self):

        if self.current <= self.end:
            value = self.current
            self.current += 1
            return value

        raise StopIteration


numbers = NumberRange(5, 10)

for number in numbers:
    print(number)

5
6
7
8
9
10

Your Tasks

1. Change the iterator so it supports a custom step.
2. Test a step of 2.
3. Add support for counting downward.
4. Make sure the iterator stops correctly.
5. Test your iterator with a for loop.
6. Test it manually using next().

Knowledge Check

Test your understanding of Python iterators.

Lesson Summary