O protocolo do iterador por dentro

Iterável e iterador não são a mesma coisa

A palavra iteração esconde dois papéis que vale separar. O iterável é o objeto que você percorre, como uma lista; ele sabe produzir, sob demanda, um iterador. O iterador é quem realmente entrega os valores um a um. A distinção fica clara com a função iter: chamar iter em uma lista devolve um iterador novo, separado da lista. A lista é a fonte; o iterador é o ponteiro que caminha por ela. Um iterável pode gerar vários iteradores independentes; cada um mantém a própria posição.

numeros = [10, 20, 30]        # a lista e um iteravel

it = iter(numeros)            # iter() devolve um iterador
print(next(it))               # 10
print(next(it))               # 20
print(next(it))               # 30
print(next(it))               # levanta StopIteration

iter() cria o iterador; next() pede o próximo valor; no fim vem StopIteration.

O ciclo é sempre esse: iter obtém um iterador, next pede o próximo valor, e quando não há mais nada, o próximo next levanta a exceção StopIteration. Repare que StopIteration não é um erro no sentido usual; é um sinal combinado que significa acabou. Entender que iterável e iterador são coisas diferentes evita confusões comuns, como esperar que um iterador esgotado volte ao começo. Ele não volta: uma vez percorrido, precisa ser recriado a partir do iterável.

O que o for faz nos bastidores

Com o protocolo em mente, o laço for perde o mistério. Quando você escreve for x in colecao, o Python faz três coisas: chama iter na coleção para obter um iterador, chama next nesse iterador repetidamente para pegar cada valor, e para quando um next levanta StopIteration, capturando essa exceção por você. Ou seja, o for é açúcar sintático sobre iter, next e um try, except invisível. Escrever o equivalente à mão deixa isso evidente.

colecao = ["a", "b", "c"]

# Isto:
for item in colecao:
    print(item)

# E equivalente a isto por baixo dos panos:
it = iter(colecao)
while True:
    try:
        item = next(it)
    except StopIteration:
        break
    print(item)

O for é iter + next repetido + captura de StopIteration, embutidos.

Criando um iterador próprio

Agora você pode criar seus próprios objetos iteráveis. A forma completa é uma classe com dois métodos: o __iter__, que devolve o iterador (muitas vezes o próprio objeto), e o __next__, que entrega o próximo valor ou levanta StopIteration quando acaba. O exemplo abaixo é uma contagem regressiva. Repare que ela guarda a posição atual em um atributo e a atualiza a cada chamada de __next__, exatamente como um ponteiro que avança.

class Regressiva:
    def __init__(self, inicio):
        self.atual = inicio

    def __iter__(self):
        return self            # o proprio objeto e o iterador

    def __next__(self):
        if self.atual <= 0:
            raise StopIteration  # sinaliza o fim
        valor = self.atual
        self.atual -= 1
        return valor

for n in Regressiva(3):
    print(n)                   # 3, 2, 1

Uma classe iteradora: __iter__ devolve self, __next__ entrega ou encerra com StopIteration.

Funciona, mas é bastante código para algo simples. Guarde essa sensação, porque é justamente ela que os geradores resolvem: na próxima aula você vai ver que uma função com yield produz o mesmo iterador com uma fração das linhas, cuidando de __iter__, __next__ e StopIteration automaticamente. Entender o protocolo à mão primeiro é o que faz o gerador deixar de ser mágica e virar uma abreviação compreensível de algo que você já sabe montar.