Python next() Function: Iterator Traversal and Fallback Values

Syntax & Parameters 🔝

next(iterator[, default])

Basic Usage: Iterators and StopIteration 🔝

To use next() on a sequence like a list or string, first convert it into an iterator using iter(). Each call advances the iterator position by one:

# 1. Create an iterator from a list
my_list = [18, 5, 15]
my_iter = iter(my_list)

print(next(my_iter))  # Output: 18
print(next(my_iter))  # Output: 5
print(next(my_iter))  # Output: 15

# 2. Calling next() once more raises StopIteration
try:
    next(my_iter)
except StopIteration:
    print("Iterator exhausted: StopIteration raised")

Output:

18
5
15
Iterator exhausted: StopIteration raised

Preventing Exceptions with the default Parameter 🔝

Passing a fallback value as the second argument suppresses StopIteration. Once all items are consumed, next() returns the fallback value safely:

letters = iter("abc")

print(next(letters, "End"))  # Output: a
print(next(letters, "End"))  # Output: b
print(next(letters, "End"))  # Output: c
print(next(letters, "End"))  # Output: End (no exception raised)
print(next(letters, "End"))  # Output: End

Common Pitfall: Iterable vs. Iterator (TypeError) 🔝

Passing a regular collection (such as a list, tuple, or dictionary) directly to next() raises a TypeError. Iterables can generate iterators, but are not iterators themselves:

raw_list = [10, 20, 30]

try:
    next(raw_list)  # raw_list is a list, not an iterator
except TypeError as e:
    print("Caught TypeError:", e)

# Correct approach: convert with iter() first
valid_iterator = iter(raw_list)
print("Correct usage with iter():", next(valid_iterator))

Output:

Caught TypeError: 'list' object is not an iterator
Correct usage with iter(): 10

Idiomatic Pattern: Finding the First Matching Item 🔝

In production Python, combining a generator expression with next() is the standard idiomatic way to retrieve the first item meeting a condition without iterating over the remaining elements:

users = [
    {"id": 1, "name": "Alice", "role": "editor"},
    {"id": 2, "name": "Bob", "role": "admin"},
    {"id": 3, "name": "Charlie", "role": "admin"}
]

# 1. Retrieve first admin user
first_admin = next((u for u in users if u["role"] == "admin"), None)
print("First Admin:", first_admin)

# 2. Safely search for a non-existent role
manager = next((u for u in users if u["role"] == "manager"), "No match found")
print("Manager search:", manager)

Output:

First Admin: {'id': 2, 'name': 'Bob', 'role': 'admin'}
Manager search: No match found

Practical Pattern: Skipping Header Rows in Data Streams 🔝

When parsing delimited CSV files or log files line-by-line, calling next() once on the iterator consumes the header row, leaving the remaining lines ready for processing:

csv_stream = [
    "id,product,price",
    "101,Keyboard,45.00",
    "102,Mouse,15.50"
]

data_iter = iter(csv_stream)

# Consume header
header = next(data_iter)
print("Header Fields:", header.split(","))

# Process remaining rows
for row in data_iter:
    print("Data Row:", row.split(","))

Output:

Header Fields: ['id', 'product', 'price']
Data Row: ['101', 'Keyboard', '45.00']
Data Row: ['102', 'Mouse', '15.50']

Custom Class Iterator Implementation 🔝

You can create custom iterable classes by implementing the Python iterator protocol with __iter__() and __next__():

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

    def __iter__(self):
        return self

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

timer = Countdown(3)
print(next(timer))  # Output: 3
print(next(timer))  # Output: 2
print(next(timer))  # Output: 1
print(next(timer, "Liftoff!"))  # Output: Liftoff!

Hands-on Exercise with Assertions 🔝

Given an inventory log, write a function that extracts the first item in stock (stock > 0) with a price under $30. Return {"item": "None", "price": 0} if no match exists, and verify with assertions:

catalog = [
    {"item": "Desk Lamp", "price": 35.00, "stock": 10},
    {"item": "Mousepad", "price": 12.50, "stock": 0},
    {"item": "USB Cable", "price": 8.00, "stock": 25},
    {"item": "Webcam", "price": 28.00, "stock": 5}
]

fallback = {"item": "None", "price": 0}

# Find first in-stock item under $30
match = next((p for p in catalog if p["stock"] > 0 and p["price"] < 30), fallback)

assert match["item"] == "USB Cable"
assert match["price"] == 8.00
print("Found Match:", match)
print("All unit assertions passed successfully!")

More Details & Related Guides 🔝

• Python Built-in Functions — Index of all standard built-in functions in Python.
• Python Iterator Protocol — Learn how iterators and the iter() function work under the hood.
• Python Generators — Creating stateful, memory-efficient streams using yield.
• Exception Handling in Python — Catching and handling runtime exceptions with try-except.
• Python for Loops — How Python iterates over collections using the iterator protocol.

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author   Watch on YouTube

Connect: