Imagine carregar um arquivo de log de 10 GB em uma lista apenas para encontrar os erros. Seu programa pode ficar sem memória antes de encontrar uma. Geradores Python resolvem isso produzindo valores sob demanda, um de cada vez, para que você possa trabalhar com dados enormes ou até mesmo intermináveis ​​quase sem memória.

Este guia mostra o que realmente acontece quando um gerador funciona, passo a passo. Executamos cada exemplo no Python 3.13 e a saída vem dessa execução. Ajuda já estar confortável com funções e loops, que nosso tutorial Python para iniciantes cobre.

O que é um gerador?

Um gerador é um tipo especial de iterador que você cria escrevendo uma função usando yield. Qualquer função com yield torna-se automaticamente uma função geradora, e chamá-la fornece um objeto gerador em vez de executar o código.

def count_up(limit):
    print("starting")
    n = 1
    while n <= limit:
        yield n
        n += 1
    print("finished")

gen = count_up(2)
print(gen)

# <generator object count_up at 0x...>

Observe que “iniciando” não foi impresso. Chamar a função criou apenas o gerador. Nada lá dentro foi executado ainda.

Como funciona o rendimento, passo a passo

Cada chamada para next() executa a função até atingir yield, devolve esse valor e congela no lugar. A próxima chamada é retomada logo após essa linha, com todas as variáveis ​​locais intactas.

print(next(gen))
# starting
# 1

print(next(gen))
# 2

next(gen)
# finished
# StopIteration

Siga a saída com cuidado. “starting” aparece apenas no primeiro next(). No segundo, a execução continua de onde parou, então n ainda está disponível e se torna 2. No terceiro, o loop termina, “terminado” é impresso, a função cai no final e o Python aumenta StopIteration para sinalizar que não resta mais nada.

Você raramente liga para next() sozinho. Um loop for faz isso por você e lida com StopIteration silenciosamente, assim como list(), sum() e funções semelhantes:

print(list(count_up(3)))

# starting
# finished
# [1, 2, 3]

rendimento vs retorno

Esse atraso é conhecido como avaliação preguiçosa: os valores são calculados apenas quando necessário. Um simples return dentro de um gerador simplesmente o encerra, o que aciona StopIteration.

A diferença de memória, medida

Comparamos uma lista de um milhão de quadrados com um gerador equivalente, usando sys.getsizeof:

import sys

squares_list = [n * n for n in range(1_000_000)]
squares_gen = (n * n for n in range(1_000_000))

print(sys.getsizeof(squares_list), sys.getsizeof(squares_gen))

# 8448728 200

A própria estrutura da lista ocupava cerca de 8,4 MB, enquanto o gerador ocupava apenas 200 bytes em nosso sistema. A lacuna real é ainda maior, pois getsizeof não conta os objetos inteiros dentro da lista. O tamanho do gerador também permanece o mesmo para um bilhão de itens, pois armazena apenas o seu estado atual e não os seus resultados.

Há uma compensação, no entanto. Uma lista pode ser reutilizada, indexada e medida com len(). Um gerador não oferece nada disso. Se você precisar de acesso aleatório ou fizer vários loops em uma pequena quantidade de dados, uma lista será mais simples. Consulte nosso guia para lista Python vs tupla vs conjunto para saber mais sobre esses tipos.

Expressões geradoras

Para casos simples, você não precisa de uma função. Uma expressão geradora se parece com uma compreensão de lista com colchetes no lugar de quadrados:

squares = [n * n for n in range(5)]   # builds a list now
squares = (n * n for n in range(5))   # produces values on demand

print(sum(n * n for n in range(5)))

# 30

Quando uma expressão geradora é o único argumento de uma função, como em sum(), você pode omitir os colchetes extras. Este é um hábito organizado para totais de dados grandes, porque nenhuma lista temporária é criada.

Crie um pipeline de dados

É aqui que os geradores realmente brilham. Pequenos geradores podem ser encadeados para que cada item flua através de cada etapa, um de cada vez:

def read_lines(lines):
    for line in lines:
        yield line.strip()

def only_errors(lines):
    for line in lines:
        if line.startswith("ERROR"):
            yield line

def messages(lines):
    for line in lines:
        yield line.split(" ", 1)[1]

log = ["INFO started\n", "ERROR db down\n",
       "ERROR disk full\n", "INFO stopped\n"]

print(list(messages(only_errors(read_lines(log)))))

# ['db down', 'disk full']

Cada etapa realiza um pequeno trabalho e pode ser testada por conta própria. No uso real, troque a lista de amostras por um arquivo aberto, porque os objetos de arquivo podem ser lidos linha por linha, como mostra nosso guia para manipulação de arquivos Python. Mesmo um log de vários gigabytes passaria com muito pouca memória.

Sequências infinitas

Uma lista não pode ser infinita, mas um gerador pode, porque só calcula o próximo valor. Use itertools.islice para pegar quantos você precisar:

import itertools

def fibonacci():
    a, b = 0, 1
    while True:
        yield a
        a, b = b, a + b

print(list(itertools.islice(fibonacci(), 8)))

# [0, 1, 1, 2, 3, 5, 8, 13]

Porém, tenha cuidado: chamar list(fibonacci()) sem limite seria executado até que sua memória acabasse. O mesmo padrão é adequado para geradores de ID, loops de pesquisa e resultados de API paginados, onde você busca a próxima página somente quando a atual acabar.

rendimento de e lotes

yield from passa para outro iterável, economizando um loop aninhado:

def chain_all(*groups):
    for group in groups:
        yield from group

print(list(chain_all([1, 2], (3, 4))))

# [1, 2, 3, 4]

Um padrão muito prático é dividir os dados em lotes de tamanho fixo, por exemplo, para inserir mil linhas em um banco de dados por vez:

def batches(items, size):
    batch = []
    for item in items:
        batch.append(item)
        if len(batch) == size:
            yield batch
            batch = []
    if batch:
        yield batch

print(list(batches(range(7), 3)))

# [[0, 1, 2], [3, 4, 5], [6]]

O final if batch garante que um grupo menor de sobras não seja perdido. Python 3.12 e posteriores também incluem itertools.batched, que faz um trabalho semelhante.

enviar, fechar e limpar

Os geradores também podem receber valores. send() retoma o gerador e o valor se torna o resultado da expressão yield. Você deve chamar next() uma vez primeiro para alcançar o primeiro yield:

def running_total():
    total = 0
    while True:
        value = yield total
        total += value

t = running_total()
next(t)
print(t.send(10), t.send(5))

# 10 15

A maioria das pessoas raramente precisa disso. Uma preocupação mais comum é a limpeza. Se você parar mais cedo, um bloco finally ainda será executado quando o gerador estiver fechado:

def tracked():
    try:
        yield 1
        yield 2
    finally:
        print("cleanup ran")

tr = tracked()
next(tr)
tr.close()

# cleanup ran

O Pytest usa exatamente essa ideia: um fixture com yield executa sua limpeza posteriormente, como nosso tutorial pytest demonstra. Da mesma forma, o decorador contextmanager da biblioteca padrão transforma um gerador em um bloco with.

Geradores em aulas

Escrever um método __iter__ como gerador é a maneira mais fácil de tornar sua própria classe iterável. Um bônus é que cada loop recebe um novo gerador, para que o objeto possa ser repetido repetidamente:

class Countdown:
    def __init__(self, start):
        self.start = start

    def __iter__(self):
        n = self.start
        while n > 0:
            yield n
            n -= 1

c = Countdown(3)
print(list(c), list(c))

# [3, 2, 1] [3, 2, 1]

Quando usar um gerador

Um gerador nem sempre é mais rápido no geral. Se você acabar usando todos os valores, o trabalho total será semelhante, e a compreensão da lista pode ser ainda mais rápida para dados pequenos porque tem menos sobrecarga por item. Os principais benefícios são o uso da memória e a obtenção dos primeiros resultados mais rapidamente.

Erros comuns

Reutilizando um gerador exausto

Isso pega quase todo mundo em algum momento. Um gerador lembra que está concluído:

g = count_up(2)
print(list(g), list(g))

# [1, 2] []

A segunda chamada obtém uma lista vazia sem nenhum erro. Chame a função novamente para obter um novo gerador ou use a abordagem de classe mostrada acima.

Esperando que o código seja executado imediatamente

def noisy():
    print("body runs")
    yield 1

n = noisy()        # nothing is printed
print(next(n))     # body runs, then 1

As verificações de argumentos no topo de um gerador não são executadas até o primeiro next(), portanto, os erros podem aparecer longe da chamada que os causou.

Outras armadilhas

• Chamada len() ou indexação. Os geradores não suportam nenhum dos dois e geram um TypeError.
• Fechar um arquivo muito cedo. Retornar um gerador de dentro de um bloco with pode significar que o arquivo fecha antes que qualquer linha seja lida. Coloque o yield dentro do bloco with.
• Envolver tudo em list(). Isso acaba com o benefício da memória.
• Usando um para dados pequenos. Uma lista simples geralmente é mais clara.

Considerações finais

Um gerador é uma função que pode pausar. Essa ideia oferece baixo uso de memória, sequências infinitas e pipelines limpos. Para colocá-lo em prática, encontre um local em seu código que construa uma lista grande apenas para percorrê-la uma vez e transforme-o em um gerador. Em seguida, tente encadear dois pequenos geradores em um arquivo de log real.

Perguntas frequentes

Continue aprendendo