How Do iter() and next() Cooperate?

The function iter() turns an iterable into an iterator, and the function next() pulls one value out of an iterator. Every for loop in Python is built from exactly these two operations.

it = iter([10, 20, 30])
print(type(it).__name__)
print(next(it))
print(next(it))

# Calling iter on something that is already an iterator returns it unchanged.
print(iter(it) is it)

# A string is iterable, but it is not an iterator.
text = iter('ab')
print(next(text))
print(next(text))

The list_iterator holds a position inside the list, so each call to next() reads the following element and moves the position along. Calling iter() on it gives back the very same object, which is why iter(it) is it is True. An iterator is already its own iterator.

The string case is the interesting one. A string is iterable, which means that it can be turned into an iterator, but the string itself is not an iterator. So next('ab') raises a TypeError while next(iter('ab')) works perfectly. That distinction is the reason why iter() is a separate step at all.

For a generator the picture is the same from the outside. Calling iter() on a generator returns the generator itself, and next() resumes it from the place where it was suspended.

An exhausted iterator raises StopIteration, and it keeps raising it every single time you ask it for another value.

it = iter([1])
print(next(it))

try:
    next(it)
except StopIteration:
    print('StopIteration - nothing left')

# It stays exhausted.
try:
    next(it)
except StopIteration:
    print('still exhausted')

# next() also accepts a default, which removes the exception entirely.
it2 = iter([])
print(next(it2, 'default'))

The first next() call consumes the only element in the list. The second one raises StopIteration, and the third one shows you that the iterator is permanently finished rather than merely empty for the moment.

StopIteration is a normal control-flow signal and not a real error, which is exactly why the for loop catches it internally and finishes cleanly. If it escaped without being handled it would look like a crash, which is why you should never call next() on an iterator without either a default value or a try block.

The default argument is the tidy way to handle it. The call next(it2, 'default') returns the default instead of raising, so you can write code that does not need an exception handler at all. The same trick is what lets you find the first item in a generator without pulling the rest of it into memory.

There is one related detail to know. If you raise StopIteration inside the body of a generator, Python turns it into a RuntimeError, because it would be ambiguous with the generator signalling its own end. That is why you should never raise StopIteration yourself to finish a generator. Use return instead.

They are two halves of the same contract. The call iter(obj) calls obj.__iter__() and returns whatever that method gives back, which must be an iterator. The call next(it) calls it.__next__() and returns the next value. So a for loop is exactly this pair of calls inside a loop, with the StopIteration exception caught to end it.

The difference between the function and the method is mostly about where you call them from. iter() is the public entry point, and it works on anything iterable. That includes objects that implement the sequence protocol through __getitem__ rather than __iter__, because Python falls back to the old-style iteration protocol in that case. __iter__ is the hook that you implement when you write your own class, and the name has to be exactly that so that the machinery can find it.

That fallback is worth knowing about. If a class defines __getitem__ but not __iter__, Python can still iterate it, by calling __getitem__ with 0, then 1, then 2, and stopping when it raises an IndexError. It works, but it is the old protocol, it is slower, and it does not give you a proper iterator object. Implementing __iter__ and __next__ explicitly is the right thing to do for any class that you write.

There is one more practical note. The next() function accepts a default, so next(it, None) returns None instead of raising StopIteration when the iterator is exhausted. That is often the cleanest way to peek at the first item of a generator, and it saves you from writing a try block for what is a completely ordinary situation.