Iterators: __iter__ & __next__

Published by Brayan K

The iterator protocol is the simple contract behind every Python loop: an iterable returns an iterator from its __iter__ method, and that iterator hands back one value per call to __next__ until it raises StopIteration to signal the end.

Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

An iterable supplies a cursor; the cursor holds the position

Think of a playlist and two listeners. The playlist stores the songs; each listener needs a separate position. In Python, the iterable supplies an iterator, and that iterator carries the traversal state. Returning a fresh iterator allows independent passes. Returning the same iterator shares its position.

songs = ["Intro", "Bridge", "Finale"]
first = iter(songs)
second = iter(songs)
print(next(first))
print(next(first))
print(next(second))
print(iter(first) is first)
print(first is second)

# ✅ Expected output:
# Intro
# Bridge
# Intro
# True
# False

Calling iter on an iterator returns that same iterator; it does not rewind it. Generator functions are a concise way to create iterators, covered in Generators & Iterators Mastery. Here we make the state transitions explicit with a class.

Write one transition for each call to next

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

    def __iter__(self):
        return self

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

cursor = Countdown(3)
print(next(cursor))
print(list(cursor))
print(list(cursor))
print(next(cursor, "finished"))

# ✅ Expected output:
# 3
# [2, 1]
# []
# finished

The guard runs before returning a value. The stored position moves exactly once for each successful request. Once exhausted, this iterator stays exhausted. The default passed to next is returned only when StopIteration occurs; it is not a general fallback for any exception raised by the iterator.

cursor = iter([])
try:
    next(cursor)
except StopIteration as error:
    print(type(error).__name__)

# ✅ Expected output:
# StopIteration

A for loop handles this signal and stops quietly. Calling next yourself exposes it unless you provide a default. A normal value such as None must not be confused with exhaustion:

cursor = iter([None, "ready"])
print(next(cursor, "finished"))
print(next(cursor, "finished"))
print(next(cursor, "finished"))

# ✅ Expected output:
# None
# ready
# finished

Returning a collection from __iter__ is not enough

class Playlist:
    def __iter__(self):
        return ["Intro", "Finale"]

list(Playlist())

# ✅ Expected error:
# TypeError: iter() returned non-iterator of type 'list'

A list is iterable but does not itself implement next. Wrap the stored collection with iter when the collection should provide repeatable passes. The collection object and its cursors then have different responsibilities.

class Playlist:
    def __init__(self, songs):
        self.songs = tuple(songs)

    def __iter__(self):
        return iter(self.songs)

playlist = Playlist(["Intro", "Finale"])
print(list(playlist))
print(list(playlist))
print([(a, b) for a in playlist for b in playlist])

# ✅ Expected output:
# ['Intro', 'Finale']
# ['Intro', 'Finale']
# [('Intro', 'Intro'), ('Intro', 'Finale'), ('Finale', 'Intro'), ('Finale', 'Finale')]

The tuple makes a snapshot of the input collection for this example. Each nested loop obtains its own cursor, so the inner loop does not consume the outer loop’s position. This design is appropriate for repeatable stored data. A live input stream may intentionally provide only one pass.

Do not reset an iterator whenever iter is called

class Steps:
    def __init__(self):
        self.position = 0

    def __iter__(self):
        return self

    def __next__(self):
        if self.position == 3:
            raise StopIteration
        self.position += 1
        return self.position

cursor = Steps()
print("First:", next(cursor))
for value in cursor:
    print("Remaining:", value)

# ✅ Expected output:
# First: 1
# Remaining: 2
# Remaining: 3

The for loop calls iter on cursor. If that method reset position to zero, the loop would repeat an item already consumed. Reuse the data by creating a new cursor, not by surprising an existing cursor’s callers. Likewise, do not return None when the cursor ends: the loop would treat it as another item and keep asking.

A class can also support Python’s older sequence iteration fallback through indexed access. This lesson uses the explicit iterator protocol so the stopping rule and state ownership are visible. It is not a claim that every iterable must define both methods on the same object.

Complete the boundaries of a short range cursor

The cursor should produce start inclusive through stop exclusive. Fill the object returned by iter, the exhaustion exception and the state update. Print it twice to confirm that a consumed cursor is not automatically reset.

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

    def __iter__(self):
        return ___

    def __next__(self):
        if self.current >= self.stop:
            raise ___
        value = self.current
        self.current += ___
        return value

cursor = ShortRange(2, 5)
print(list(cursor))
print(list(cursor))

# 👉 replace ___ with self
# 👉 replace ___ with StopIteration
# 👉 replace ___ with 1

# ✅ Expected output:
# [2, 3, 4]
# []

Give two readers independent passes over records

Build a Records iterable that snapshots A, B and C and returns a new RecordCursor from every call to iter. RecordCursor should hold its own position, return itself from iter and stop at the end. Advance the first reader twice, advance the second once, then print what remains for each. Finally print all records from a fresh pass. Keep traversal state out of Records.

class RecordCursor:
    def __init__(self, records):
        self.records = records
        self.position = 0

    def __iter__(self):
        return self

    def __next__(self):
        if self.position >= len(self.records):
            raise StopIteration
        value = self.records[self.position]
        self.position += 1
        return value

class Records:
    def __init__(self, records):
        self.records = tuple(records)

    def __iter__(self):
        return RecordCursor(self.records)

records = Records(["A", "B", "C"])
first = iter(records)
second = iter(records)
print(next(first), next(first))
print(next(second))
print(list(first))
print(list(second))
print(list(records))

# ✅ Expected output:
# A B
# A
# ['C']
# ['B', 'C']
# ['A', 'B', 'C']

This class is deliberately explicit so you can inspect who owns the position. For a simple wrapper over a tuple, returning iter(self.records) would be shorter and equally suitable; the custom cursor becomes useful when each step requires its own additional behavior.

Practice quiz

What does this program print? values = [1, 2] a = iter(values) b = iter(values) print(next(a), next(a), next(b))

  • 1 2 1
  • 1 2 2
  • 1 1 1
  • 2 1 2

Answer: 1 2 1. Each newly created iterator has its own position.

What does this program print? it = iter([1, 2]) print(next(it)) print(iter(it) is it) print(list(it))

  • 1 False [1, 2]
  • 1 True [1, 2]
  • 1 True [2]
  • 1 False [2]

Answer: 1 True [2]. iter returns the cursor itself without rewinding it.

What does this program print? it = iter([None]) print(next(it, "end")) print(next(it, "end"))

  • end end
  • None None
  • end None
  • None end

Answer: None end. None is an item; the default appears only after exhaustion.

What does this program print? it = iter([1, 2]) print(list(it)) print(list(it))

  • [1, 2] [1, 2]
  • [1, 2] []
  • [1] [2]
  • [] []

Answer: [1, 2] []. The first list call consumes the cursor.

What should __iter__ return on a custom iterator object?

  • A list of all remaining items
  • None when finished
  • The iterator itself
  • A reset position

Answer: The iterator itself. An iterator returns itself and preserves its current progress.

Which error ends this program? class Bad: def __iter__(self): return [1, 2] list(Bad())

  • TypeError: iter() returned non-iterator of type 'list'
  • StopIteration
  • TypeError: object is not callable
  • [1, 2]

Answer: TypeError: iter() returned non-iterator of type 'list'. The returned list is iterable but is not an iterator.

Why should a reusable collection return fresh cursors?

  • To sort every pass
  • To avoid implementing __init__
  • To make None stop a loop
  • To keep independent passes from sharing a position

Answer: To keep independent passes from sharing a position. Independent readers should not consume each other’s traversal state.

What does this program print? it = iter([]) print(next(it, "done"))

  • None
  • done
  • StopIteration
  • []

Answer: done. The default is returned instead of raising exhaustion.

Continue this course

Related lessons