Iteráveis versus iteradores: o protocolo por trás dos laços for

O que é

A referência da biblioteca documenta dois métodos. Um iterável fornece __iter__(), que devolve um iterador; um iterador fornece __next__(), que devolve o próximo item ou lança StopIteration, e o seu próprio __iter__(), que devolve o próprio iterador. Um laço for chama iter() uma vez e next() repetidamente. A consequência: um contêiner devolve um iterador novo a cada chamada de iter(), enquanto um iterador entregue a um segundo laço devolve a si mesmo e parece vazio, porque já está esgotado. A referência acrescenta que, depois de __next__() lançar StopIteration, ele deve continuar a fazê-lo, e classifica como "broken" (quebradas) as implementações que não o fazem. iter(callable, sentinel) cria um iterador que chama uma função até ela devolver o sentinela, e next(it, default) devolve um valor padrão em vez de lançar a exceção.

Por que importa

Funções que pedem "uma sequência" muitas vezes aceitam qualquer iterável e depois falham quando iteram duas vezes (len(), uma passagem de validação seguida de uma de processamento, testes de pertencimento). Saber qual dos dois se tem em mãos, e qual deles a assinatura promete, elimina toda uma classe de bugs de resultado vazio.

Como aplicar

• Anote parâmetros como Iterable[T] para uma única passagem e como Sequence[T] ou Collection[T] quando forem necessários len, indexação ou várias passagens; em caso de dúvida, materialize uma vez com list(xs) na fronteira.
• Implemente __iter__ como função geradora em contêineres personalizados; cada chamada produz um iterador novo e independente, sem precisar escrever à mão uma classe de iterador.
• Escreva uma classe de iterador apenas quando ela precisar de um estado que um gerador não consegue expressar (espiar o próximo item, voltar ao início, controle externo), e faça __iter__ devolver self.
• Leia blocos de tamanho fixo com iter(partial(f.read, 4096), b""); a documentação das funções embutidas mostra esse idioma de leitura em blocos.
• Obtenha o primeiro elemento com segurança usando next(it, None); para pular elementos, use itertools.islice.
• Materialize entradas preguiçosas (lazy) antes de novas tentativas ou de uma validação que precede o uso; caso contrário, ambos consumiriam os dados.

Armadilhas

isinstance(x, Iterable) não diz nada sobre a possibilidade de reiterar; um gerador passa no teste e mesmo assim se esgota. Arquivos abertos são iteradores sobre linhas: um segundo for line in f não produz nada sem f.seek(0). map, filter, zip, enumerate e reversed devolvem iteradores de passagem única, ao passo que range, as views de dict e outros contêineres continuam reiteráveis. Desde a PEP 479, uma StopIteration que escapa do corpo de um gerador vira RuntimeError, portanto chamadas a next() dentro de geradores precisam de um valor padrão ou de um try. Uma classe com __getitem__ que aceita inteiros a partir de 0 é iterável pelo protocolo de sequência mais antigo, mesmo sem __iter__.