Barra de Progresso em Python: Aprenda a usar a biblioteca tqdm

Você já executou um script de processamento de dados e ficou encarando o cursor no terminal, sem saber se o código travou, se está quase acabando ou se vai demorar horas?

Essa incerteza é um problema clássico, não apenas da experiência ao não ter uma barra de progresso para quem executa o script, mas também de observabilidade. Ao lidar com grandes volumes de dados ou iterações complexas, a cegueira sobre o andamento da tarefa impede diagnósticos de melhorias e tomada de decisão.

É aqui que entra o tqdm. Muito mais do que um “efeito visual”, ele é uma ferramenta essencial para desenvolvedores Python diagnosticarem a saúde de seus loops.

O que é tqdm e como ele pode te ajudar

A biblioteca tqdm envolve seus loops e fornece métricas em tempo real. Ao utilizá-la, você ganha três insights imediatos que o cursor piscando não te dá:

1. Detecção de Lentidão: Se a velocidade de iteração (it/s) cair drasticamente, você sabe na hora que seu script encontrou um gargalo ou um dado complexo.
2. Estimativa de Tempo: O tqdm calcula quanto tempo falta para a conclusão, permitindo que você decida se espera ou se vai tomar um café.
3. Sanidade do Processo: A barra andando é a confirmação visual de que o script não travou.

Como instalar o tqdm com pip?

No Google Colab, como mostramos na imagem acima, basta importar o tqdm e envolver os seus loops. Agora caso esteja em um ambiente local, no VS Code, Jupyter ou PyCharm, basta executar no seu terminal:

pip install tqdm

pip install tqdm

Barra de progresso: Implementação básica do tqdm

Vamos supor que a sua task é executar um time.sleep de 100ms no Python por 100 vezes usando for:

import time

for i in range(100):
    time.sleep(0.1)

import time

for i in range(100):
    time.sleep(0.1)

A incorporação do tqdm é bem simples e pouco intrusiva, você terá que fazer alterações minúsculas no seu código:

from tqdm import tqdm
import time

# for envolvido com tqdm()
for i in tqdm(range(100), desc="Processando Arquivos"):
    time.sleep(0.1)

from tqdm import tqdm
import time

# for envolvido com tqdm()
for i in tqdm(range(100), desc="Processando Arquivos"):
    time.sleep(0.1)

Observe que adicionamos o parâmetro desc="Processando Arquivos". Isso ajuda a identificar qual etapa do pipeline está rodando, caso você tenha várias barras de progresso sequenciais.

Outros exemplos com tqdm

Supondo agora que você tem uma iteração sobre uma lista de nomes, que em seguida dispara um e-mail. Sua implementação seria algo como esse exemplo abaixo:

from tqdm import tqdm
import time

usuarios = ["Ana", "Bruno", "Carlos", "Daniela", "Eduardo"]

for usuario in tqdm(usuarios, desc="Enviando E-mails"):
    time.sleep(1) # Simulando envio
    # Lógica de envio aqui

from tqdm import tqdm
import time

usuarios = ["Ana", "Bruno", "Carlos", "Daniela", "Eduardo"]

for usuario in tqdm(usuarios, desc="Enviando E-mails"):
    time.sleep(1) # Simulando envio
    # Lógica de envio aqui

Resultado:

Muito provavelmente você utiliza bastante o .apply() do Pandas para analisar dados e aplicar uma alteração em cada linha ou coluna do seu dataset.

O tqdm tem uma extensão do apply() que é o progress_apply():

Com isso, você também consegue acompanhar a sua etapa de transformação de dados em um ETL escrito em Python, por exemplo.

Conclusão

Com zero custo de implementação, você transforma um script em uma ferramenta mais profissional e que comunica seu estado.

Recentemente eu desenvolvi um script para processar um .csv com ~6.5 milhões de linhas e acabou ficando muito lento – o tqdm foi útil para diagnosticar a taxa de iteração por segundo, que estava na casa de 5.000 it/s.

Depois de algumas melhorias, a taxa de iteração por segundo foi de 5.000 it/s para 170.000 it/s. O que antes levava mais de 20 minutos para ser concluído, passou para menos de 30 segundos.

Esperamos que tenha curtido, conheça outras dicas como essa na nossa categoria de Python.