O que é um iterável

O que o for percorre de verdade

Desde o Básico você escreve for item in lista sem pensar no que acontece por dentro. Está na hora de abrir essa caixa, porque entender o mecanismo é o que permite criar as suas próprias sequências no restante deste módulo. A ideia central é simples: o for não sabe nada sobre listas em particular. Ele conhece um protocolo, um acordo, que qualquer objeto pode cumprir. Quem cumpre esse acordo é percorrível pelo for. Cumprir o acordo significa duas coisas: saber entregar um iterador quando alguém chama iter(), e esse iterador saber entregar o próximo item quando alguém chama next().

Vale separar dois nomes que parecem iguais e não são. O iterável é a coleção, a fonte: a lista [1, 2, 3]. O iterador é o caminhante que anda por ela, guardando onde parou. Uma lista sozinha não guarda posição; você pode percorrê-la duas vezes do começo. O iterador, sim, guarda posição: depois que ele entrega o último item, acabou para ele. Essa distinção fica clara quando você faz o trabalho do for na mão, como no exemplo a seguir.

numeros = [10, 20, 30]

andarilho = iter(numeros)   # pede um iterador para a lista
print(type(andarilho))      # <class 'list_iterator'>

print(next(andarilho))      # 10
print(next(andarilho))      # 20
print(next(andarilho))      # 30

iter() devolve o iterador; cada next() entrega o próximo item, na ordem.

StopIteration, o fim de linha

E quando os itens acabam? O iterador precisa avisar de algum jeito que não há próximo. Em vez de devolver um valor especial, que poderia se confundir com um dado real, ele levanta uma exceção chamada StopIteration. É um sinal, não um erro de verdade a se preocupar. O for está o tempo todo esperando por esse sinal: quando ele chega, o laço termina de forma limpa, sem que você precise contar itens nem verificar tamanho.

letras = iter("oi")

print(next(letras))   # o
print(next(letras))   # i
print(next(letras))   # levanta StopIteration

# Traceback (most recent call last):
#   ...
# StopIteration

Depois do último item, next() levanta StopIteration para dizer que acabou.

Agora dá para enxergar o for como açúcar sintático em cima desse protocolo. Escrever for x in fonte é o mesmo que, nos bastidores, pegar um iterador com iter(fonte), chamar next() dentro de um laço, guardar cada valor em x e parar quando o StopIteration aparece. Você nunca precisa escrever isso na mão no dia a dia, e é bom que seja assim. Mas conhecer o mecanismo muda tudo, porque no próximo passo você vai construir objetos que produzem itens sob demanda, cumprindo exatamente esse acordo, com uma palavra nova chamada yield.

Fixando a ideia

Antes de seguir, vale amarrar o conceito. Um iterável entrega um iterador quando você chama iter(). O iterador entrega itens quando você chama next(), um de cada vez, e levanta StopIteration ao terminar. O for orquestra isso tudo por você. Guardar essa sequência de eventos é o que faz a próxima aula, sobre funções geradoras, cair como uma luva, porque o gerador é justamente um jeito prático de criar um iterador sem escrever nenhuma dessas peças na mão.