Produzir valores sob demanda com yield

Uma função cujo corpo contém yield é uma função geradora. Ela oferece uma forma concisa de criar um iterador, sem escrever manualmente uma classe com __iter__ e __next__.

Nesta definição, primeiro_numero é a função geradora — o corpo ainda não foi executado.

Não confunda definir a função, chamá-la e pedir seu próximo valor: são operações distintas.

A chamada primeiro_numero(10) cria um objeto gerador e o associa a gerador. Ela não imprime "Corpo iniciado".

A primeira chamada de next(gerador) inicia o corpo até alcançar yield. Portanto, a saída é:

Gerador criado
Corpo iniciado
10

O objeto gerador já é um iterador: funciona com iter, next e for, sem que você implemente esses métodos.

Dentro de uma função geradora, yield calcula ou obtém um valor, entrega esse valor a quem consome o gerador e pausa a execução. Em um laço, isso permite produzir vários resultados: cada passagem alcança um novo yield.

Diferentemente de criar uma lista com todos os resultados antes, a função abaixo calcula cada dobro quando esse valor é solicitado.

yield entrega um valor sem encerrar a função geradora, então o laço pode seguir para outra iteração quando houver uma nova solicitação.

Já return encerra a execução naquele ponto. Se ele substituir yield no corpo do laço, nenhum valor será entregue por essa instrução e não haverá próxima passagem do laço nessa execução.

No seu editor, crie a função quadrados do exercício. Em seguida, crie gerador = quadrados(4) e execute quatro chamadas a next(gerador). Você deve observar, em ordem: 0, 1, 4 e 9.

A função não monta uma lista de quadrados: o cálculo de cada expressão ocorre durante o consumo, quando a execução alcança seu respectivo yield.

Quando next() avança um gerador, o corpo executa até alcançar o próximo yield. Nesse ponto, o valor é entregue e a execução fica suspensa.

As variáveis locais continuam guardadas no objeto gerador. Na próxima chamada de next(), o Python retoma logo depois do yield que entregou o valor anterior — não no início da função.

Execute uma chamada de cada vez e observe a posição em que o corpo para.

O diagrama mostra que cada chamada de next() retoma o mesmo percurso no ponto onde ele havia parado.

Uma função geradora pode ser chamada várias vezes. Cada chamada cria um novo objeto gerador, com suas próprias variáveis locais e seu próprio ponto de suspensão.

Assim, pares(0) e pares(10) executam o mesmo código, mas não compartilham contador nem progresso.

Agora, as chamadas a next são intercaladas. Cada uma retoma apenas o objeto recebido como argumento.

Um yield entrega um elemento e suspende a função. O término normal só é percebido quando uma chamada posterior de next() retoma o corpo e ele chega ao fim — ou encontra um return sem valor.

Por isso, receber o último valor não significa que o consumidor já observou StopIteration: em geral, é preciso pedir mais um valor.

A imagem separa a entrega final do avanço que confirma o esgotamento.

Execute cada bloco separadamente para observar os avanços.

Nos dois casos, a saída é único valor e depois ESGOTADO. O return sem valor encerra a função; ele não produz None como próximo elemento.

O argumento padrão de next permite observar o esgotamento sem deixar StopIteration interromper o programa.

Mesmo com yield escrito na função, este caminho pode terminar antes de alcançá-lo.

A chamada cria o objeto normalmente. Porém, no primeiro avanço, a condição é atendida e o return encerra o corpo antes de qualquer yield. Assim, a geração é vazia.

Um print dentro de uma função geradora só acontece quando a execução chega àquela linha. Portanto, criar o objeto com etapas() não mostra nenhuma mensagem do corpo: o primeiro next() é que inicia a execução.

Depois de um yield, o gerador fica pausado. As linhas abaixo dele continuam pendentes até uma nova solicitação de valor.

Execute este exemplo no seu Python 3.

A execução avança somente até o próximo ponto de suspensão.

Se você executar apenas next(fluxo) uma vez, verá início do corpo e receberá primeiro. Nesse ponto, o gerador está suspenso no primeiro yield.

Assim, entre os valores e fim do corpo ainda não foram impressos. Elas são instruções pendentes, não mensagens já produzidas.

No código anterior, deixe somente estas linhas depois de fluxo = etapas():

print("gerador criado")
print(next(fluxo))

Execute o arquivo. Interrompa aí: não faça o segundo next(). Compare a saída com o corpo da função e identifique quais print continuam pendentes.

Uma chamada a uma função geradora cria o objeto gerador, mas não percorre seu corpo. Portanto, uma validação escrita no corpo só ocorre quando algum consumo — como next() — alcança essa linha.

Se a validação vier antes do primeiro yield, a exceção aparecerá no primeiro avanço, e não na chamada que criou o gerador.

Uma exceção pode ocorrer depois de valores já entregues. Nesse caso, os avanços anteriores funcionam; a chamada de next() que alcança a falha recebe a exceção.

Quando uma exceção do corpo não é tratada, ela se propaga ao consumidor e aquele objeto gerador fica encerrado. Diferentemente do término normal, não é um sinal de que a sequência terminou como planejado.

No seu computador, crie um arquivo Python e implemente quadrados_ate(limite). Ela deve produzir os quadrados de 0 até limite - 1, um por vez, sem montar uma lista. Para tornar a execução observável, mantenha as mensagens antes e depois de cada yield.

A validação do limite fica no corpo da função: por isso, um limite negativo só gera erro quando o objeto é avançado pela primeira vez.

Execute este roteiro completo. Leia as mensagens junto com os valores: elas revelam quais trechos do corpo foram realmente alcançados. Observe especialmente que criar negativo não falha; a falha aparece no next(negativo).