Python: iterator

An iterator provides data-items to its user, one at a time.

The next item is returned by calling the iterator's __next__ method.

__next__ throws a StopIteration exception when there are no more items to be returned.

Python provides the next(iter) built-in function that calls iter.__next__() under the hood and passes the returned value to the callor of next().

An iterator is also required to implement the __iter__() method which returns the iterator itself.

An iterator is different from a container object (such as list) in that the iterator only allows to be iterated over once while the __iter()__ method of a list returns a new iterator and thus can be iterated over multiple times.