itertools.accumulate() produz resultados acumulados enquanto percorre um iterável. Por padrão, ele calcula somas progressivas, mas também aceita qualquer função binária adequada, como multiplicação, máximo, mínimo ou uma regra de estado personalizada. Como retorna um iterador, funciona bem em pipelines e fluxos de dados grandes.
Neste guia, você verá somas cumulativas, o parâmetro initial, funções de operator, saldos, máximos progressivos, médias acumuladas e cuidados com tipos mutáveis.
Soma acumulada
from itertools import accumulate
valores = [10, 5, -2, 8]
print(list(accumulate(valores)))
# [10, 15, 13, 21]
Cada resultado combina o acumulado anterior com o próximo item.
Valor inicial
print(list(accumulate([5, 7, 3], initial=100)))
# [100, 105, 112, 115]
Com initial, o primeiro elemento emitido é o valor inicial. Isso é útil para saldos, posições e estados que começam antes do primeiro evento.
Multiplicação acumulada
from operator import mul
fatores = [2, 3, 4]
print(list(accumulate(fatores, mul)))
# [2, 6, 24]
Máximo progressivo
temperaturas = [18, 20, 19, 24, 22]
recordes = accumulate(temperaturas, max)
print(list(recordes))
# [18, 20, 20, 24, 24]
Esse padrão encontra o maior valor observado até cada posição.
Saldos após transações
movimentos = [200, -50, -25, 100]
saldos = accumulate(movimentos, initial=1000)
for saldo in saldos:
print(saldo)
O resultado inclui o saldo inicial e cada estado posterior.
Função personalizada
def limitar(acumulado, valor):
return max(0, acumulado + valor)
print(list(accumulate([-3, 8, -20, 5], limitar, initial=10)))
A função recebe o acumulado atual e o novo item. Ela deve retornar o próximo estado.
Iteração preguiçosa
accumulate não cria todos os resultados antecipadamente. Você pode combinar o iterador com islice, filtros e outras ferramentas de itertools.
from itertools import accumulate, islice
primeiros = islice(accumulate(gerar_eventos(), atualizar_estado), 100)
Média acumulada
Para médias, acumule soma e quantidade em uma tupla.
def atualizar(estado, valor):
soma, quantidade = estado
return soma + valor, quantidade + 1
estados = accumulate([10, 20, 15], atualizar, initial=(0, 0))
medias = [soma / n for soma, n in estados if n]
Estados imutáveis são mais seguros
Evite modificar e devolver o mesmo dicionário ou lista a cada passo, pois todos os resultados podem apontar para o mesmo objeto. Prefira tuplas, dataclasses imutáveis ou cópias explícitas.
accumulate versus sum
sum entrega apenas o total final. accumulate entrega cada estado intermediário. Use-o quando a trajetória for importante.
accumulate versus reduce
functools.reduce também combina itens, mas retorna apenas um resultado final. accumulate expõe a sequência completa dos acumulados.
Precisão numérica
Somas de muitos floats podem acumular erro de arredondamento. Para dinheiro ou precisão decimal, considere decimal.Decimal. Para uma soma final mais precisa de floats, math.fsum pode ser melhor, embora não produza estados intermediários.
Erros comuns
- Esquecer que
initialadiciona um elemento ao resultado. - Usar uma função com argumentos na ordem errada.
- Modificar o mesmo acumulador mutável.
- Converter um fluxo infinito inteiro em lista.
- Esperar que o resultado seja um valor, e não um iterador.
Boas práticas
Mantenha a função acumuladora pura, use estados pequenos e imutáveis, documente o significado de initial e consuma o iterador progressivamente. Leia também os guias internos sobre itertools no Python, groupby e pairwise.
Conclusão
itertools.accumulate é ideal para totais progressivos e máquinas de estado simples. Sua natureza preguiçosa permite processar grandes fluxos, enquanto funções personalizadas tornam a ferramenta útil muito além de somas.
