Barras de progresso em Python: Um guia completo com exemplos

Nos aplicativos atuais, os usuários querem feedback imediato, especialmente quando as tarefas levam muito tempo para serem concluídas. As barras de progresso do Python são uma maneira clara e fácil de mostrar que algo está acontecendo em segundo plano. Uma barra de progresso forte ajuda o programa a parecer mais rápido, acrescenta um toque profissional e melhora a facilidade de uso. 

Neste artigo, você aprenderá a implementar barras de progresso em Python usando bibliotecas populares como tqdm, progress, progressbar2, alive-progress e Tkinter, juntamente com as práticas recomendadas para melhorar a experiência do usuário e o desempenho do aplicativo.

Para saber mais sobre os conceitos do Python de forma prática, confira nosso curso de habilidades programa de habilidades Fundamentos da Programação Python.

O que são barras de progresso em Python?

As barras de progresso são onipresentes. Eles são frequentemente usados para downloads de arquivos, instalações de software e pipelines de ETL. Eles também são úteis para acompanhar o progresso do treinamento do modelo de machine learning.

A barra de progresso exibe o quanto de uma tarefa está concluída e o quanto resta. Ele pode aparecer como texto em uma interface de linha de comando (CLI) ou como uma barra visual em uma interface gráfica do usuário (GUI).

As barras de progresso melhoram a experiência do usuário. Eles fornecem atualizações em tempo real, mostrando aos usuários seu progresso no processo. Se ocorrer um atraso, os usuários podem decidir se querem intervir ou esperar. Essa visibilidade reduz a frustração e faz com que os tempos de espera pareçam mais curtos. Os usuários não ficam olhando para uma tela estática, imaginando se algo está acontecendo; eles permanecem envolvidos e se sentem seguros de que o progresso está acontecendo.

Os desenvolvedores usam barras de progresso para acompanhar o desempenho do aplicativo. Eles ajudam a identificar gargalos, código de benchmark e rastrear a duração da tarefa. As barras de progresso em scripts e fluxos de trabalho mostram atualizações claras de status. Eles ajudam os usuários a entender melhor os processos de longa duração. Eles também aprimoram a usabilidade de ferramentas interativas e notebooks.

As barras de progresso também podem servir como uma forma simples de monitoramento de desempenho. Eles mostram o tempo que cada tarefa leva. Isso ajuda os desenvolvedores a identificar estágios lentos e medir a eficiência. Isso permite a comparação fácil de diferentes implementações. 

Barras de progresso da linha de comando

As barras de progresso da linha de comando fornecem feedback visual para tarefas de longa duração diretamente no terminal, tornando os scripts mais informativos e fáceis de usar. O Python oferece várias bibliotecas, cada uma com pontos fortes em termos de velocidade, personalização e estilo visual. Examinaremos quatro deles: tqdm, progress, progressbar2, e alive-progress. 

Tqdm: o padrão de velocidade e simplicidade

tqdm é uma biblioteca popular em Python para criar barras de progresso. Ele fornece indicadores de progresso rápidos e versáteis para loops e iteráveis. Ele programa as iterações e calcula o tempo restante e o tempo decorrido. Essas informações atualizam a barra em tempo real. tqdm opera em segundo plano. Ele prevê quanto tempo resta e ignora as atualizações que não são necessárias. É simples de aprender, leve no uso da memória e tem o apoio de uma comunidade sólida. 

Processo de instalação

Uma maneira fácil de instalar o tqdm é usar o instalador do pip. Digite o seguinte comando no terminal.

pip install tqdm

Imprima o número da versão para garantir que a biblioteca esteja instalada corretamente.

import tqdm
print(tqdm.__version__)

4.67.1

Uso básico do tqdm

tqdm é simples de usar. Importar a biblioteca. Envolva qualquer iterável com tqdm(iterável) para exibir uma barra de progresso.

Em vez de escrever tqdm(range(n)), você pode usar a abreviação trange(n) por conveniência.

from tqdm import trange
import time

for _ in trange(100, desc="Processing"):
    # Do stuff here
    time.sleep(0.05)  # simulate a task

Esse código produz uma barra de progresso ao vivo durante a execução.

A barra de progresso mostra

• Porcentagem concluída (22%)
• Número de iterações concluídas do total (224/1000)
• Tempo decorrido e tempo restante estimado (12 segundos decorridos, 42 segundos restantes)
• Iterações por segundo (18,09 it/s).

Para adicionar uma descrição à barra de progresso, especifique a opção desc.

for i in trange(1000, desc='Processing'):  # description
    # Simulate a task
    time.sleep(0.05)

Barras de progresso aninhadas 

As barras de progresso aninhadas no tqdm ajudam você a acompanhar o progresso em vários loops. Eles também são úteis quando você precisa monitorar vários estágios de trabalho. Os exemplos incluem processamento em lote, loops aninhados e treinamento de modelos. 

Envolva cada loop em um loop aninhado com tqdm. Use os argumentos position e leave para controlar como eles aparecem.

• position: Define a posição vertical de cada barra de progresso. position=0 é a barra mais alta, position=1 aparece abaixo dela e assim por diante.
• leave: Se leave=True, a barra de progresso permanecerá na tela após a conclusão. Se leave=False, ele desaparecerá para evitar desordem.

for i in trange(3, desc='Outer loop', leave=True):
    for j in trange(5, desc='Inner loop', leave=False):
        for j in trange(4, desc='Inner inner loop', leave=False):
            time.sleep(0.05)

As barras de progresso aninhadas mostram uma hierarquia clara. Eles ajudam você a visualizar os diferentes estágios de uma tarefa. Eles fornecem percepções detalhadas em vários níveis. Isso ajuda os desenvolvedores a identificar lentidão ou gargalos com facilidade.

Integração do Pandas

O Tqdm se integra bem ao pandas. Ele oferece uma maneira direta de adicionar barras de progresso a tarefas de DataFrame e séries. Ele mostra o progresso em tempo real de funções como apply, groupby e map. Essas funções podem ser lentas com grandes conjuntos de dados.

Para ativar esse recurso, chame tqdm.pandas(). Em seguida, use progress_apply em vez do método regular apply do pandas. Isso mostrará uma barra de progresso à medida que a função for executada em linhas ou colunas. Você verá o progresso da operação sem reescrever seu código.

No programa a seguir, criamos um DataFrame com uma coluna chamada "numbers" (números). Essa coluna contém números inteiros que variam de 0 a 1000. Em seguida, geramos uma nova coluna aplicando uma operação "lenta" chamada slow_squared. 

Em vez de usar a função padrão do pandas apply, usamos progress_apply do tqdm. Uma barra de progresso é exibida durante a operação. Ele fornece atualizações em tempo real sobre a quantidade de processamento concluída.

import pandas as pd
from tqdm import tqdm
import time

# Simulate a time-consuming operation
def slow_square(x):
    time.sleep(0.01)
    return x**2

# Create a sample DataFrame
df = pd.DataFrame({'numbers': range(1000)})

# Initialize tqdm for pandas
tqdm.pandas(desc="Processing")

# Use progress_apply instead of apply
df['slow_squared'] = df['numbers'].progress_apply(slow_square)
# Print the result
print(df.head())

O resultado do código é o seguinte.

Você pode usar progress_apply para outras operações de DataFrame, como groupby.

grouped = df.groupby('numbers').progress_apply(lambda g: g.sum())

Opções de personalização

O Tqdm permite que você personalize as barras de progresso para atender a vários ambientes e necessidades do usuário. Você pode ajustar a largura com ncols. O site bar_format argument oferece a você controle total sobre o layout do texto. Além disso, a configuração dynamic_ncols=True faz com que a barra seja redimensionada automaticamente para se ajustar ao terminal.

Considerações de desempenho específicas para a tqdm

O Tqdm é rápido e leve. Isso adiciona pouca sobrecarga, mesmo em loops rápidos. Você pode desativar as barras de progresso com disable=True. Isso é útil em configurações de produção em que o desempenho é fundamental. Para loops rápidos, atualizar a barra a cada vez pode ser demais. Portanto, o tqdm permite que você controle a frequência de atualização. Você pode usar parâmetros como mininterval e maxinterval. 

Progresso: Estilos e botões giratórios personalizáveis

O progresso Progress em Python permite que você crie facilmente barras de progresso baseadas em texto para a linha de comando. Ele apresenta uma API simples. Ele oferece suporte a barras de progresso e spinners e permite a personalização básica da saída. Ele é pequeno, rápido e não tem dependências. Isso o torna excelente para scripts rápidos e configurações simples. 

A biblioteca progress inclui sete estilos incorporados de barras de progresso: Bar, ChargingBar, FillingSquaresBar, FillingCirclesBar, IncrementalBar, PixelBar e Shadybar. 

Para configurar, use o pip install.

pip install progress

Para usar, importe o estilo desejado, instancie uma variável, use .next() no loop e .finish() depois que o processo estiver concluído. Por exemplo, para usar uma ChargingBar, use o seguinte código.

import time
from progress.bar import ChargingBar
bar = ChargingBar('Processing', max=20)
for i in range(20):
    # Do some work
    time.sleep(0.5)
    
    bar.next()
bar.finish()
`

Progress também inclui rodinhas para tarefas de duração desconhecida. O código para implementar um spinner é simples.

import time
from progress.spinner import Spinner

spinner = Spinner('Processing... ')

# Spinner during a task of unknown duration.
for _ in range(50): 
    # Do stuff 
    time.sleep(0.1)  # simulate a running task

    spinner.next()

spinner.finish()

Esse código resulta na descrição ("Processing...") seguida de um botão giratório.

A biblioteca progress é simples e leve, mas você deve levar em conta algumas limitações. Ele não é compatível com notebooks Jupyter e não pode ser redimensionado dinamicamente. Além disso, ele oferece menos opções de personalização do que bibliotecas como a tqdm. Ele funciona bem para tarefas básicas de linha de comando, mas pode ter dificuldades com trabalhos complexos ou de alto desempenho.

Progressbar2: Personalização e compatibilidade aprimoradas

Progressbar2 é uma poderosa biblioteca Python. Ele ajuda você a criar barras de progresso flexíveis e personalizáveis para aplicativos de linha de comando. Ele tem muitos widgets, como porcentagem, ETA, marcadores animados e contadores. Isso o torna excelente para tarefas de CLI mais complexas ou refinadas. 

O Progressbar2 oferece mais opções de controle e formatação do que as bibliotecas mais simples, como a Progress. Ele também funciona melhor com fluxos de trabalho de registro e multithread.

Para instalar, use o pip install.

pip install progressbar2

A classe ProgressBar em progressbar2 mostra o estado atual do progresso. Ele faz isso com um conjunto de widgets personalizáveis. 

Um widget é uma parte modular que é atualizada com base no estado da barra de progresso. Isso inclui a porcentagem de conclusão, o tempo decorrido e o tempo estimado restante. 

Você pode escolher entre vários tipos de widgets. Isso inclui rótulos de texto, marcadores de progresso, contadores, cronômetros, spinners e formatadores personalizados. Essa variedade permite que você personalize a aparência e a função da barra para o seu aplicativo.

O uso básico do Progressbar2 é bastante simples. 

import time
import progressbar

for i in progressbar.progressbar(range(1000)):
    time.sleep(0.02)

A saída exibe a porcentagem concluída, as iterações concluídas/total de iterações, o tempo decorrido e o tempo restante estimado.

As bibliotecas de barras de progresso normalmente dependem da atualização de uma única linha no terminal usando retornos de carro (\r). Isso significa que os comandos regulares do print() podem interferir, empurrando a barra para baixo ou corrompendo sua saída. A biblioteca progressbar2 oferece uma maneira de imprimir mensagens com segurança sem interferir na barra de progresso.

import time
import progressbar

bar = progressbar.ProgressBar(redirect_stdout=True)
for i in range(10):
    # Do some task
    time.sleep(0.1)

    # Print statement
    print(f'Loop #{i}')
    bar.update(i)

A biblioteca progressbar2 oferece ampla personalização por meio de seu sistema modular de widgets. Os widgets mostram detalhes na barra de progresso, incluindo a porcentagem concluída, o tempo decorrido, o tempo restante estimado, contadores ou animações da barra. Você pode misturar e combinar esses widgets para criar uma barra de progresso personalizada. Por exemplo, você pode mostrar a porcentagem e o ETA. Ou você pode adicionar mais detalhes, como nomes de arquivos, carimbos de data e hora ou spinners. 

import time
import progressbar

# Define a custom set of widgets
widgets = [
    'Progress: ',                                # Description text
    progressbar.Percentage(),         # Show percentage completed
    ' ',                              
    progressbar.Bar(marker=':'),      # Custom bar with specified marker
    ' ',
    progressbar.ETA(),                    # Estimated time remaining
    ' | ',
    progressbar.Timer(),                  # Time elapsed
]

# Initialize the progress bar with widgets
bar = progressbar.ProgressBar(widgets=widgets, max_value=50)

# Task
for i in range(50):
    # Do stuff
    time.sleep(0.1)  # Simulate task
    
    bar.update(i + 1)

Alive-progress: animações dinâmicas para terminais modernos

O Alive-progress mostra barras de progresso animadas que mudam em tempo real. Isso dá aos aplicativos de linha de comando uma aparência moderna e responsiva. A barra avança e mostra métricas úteis em tempo real. Ele exibe a porcentagem de conclusão, o tempo decorrido, o tempo restante estimado e a velocidade de iteração. Isso o torna atraente e informativo.

Para instalar o alive-progress você pode instalá-la com o pip.

pip install alive-progress

Conforme mostrado em sua página do GitHub, para ver uma demonstração de seus recursos, use o seguinte código.

from alive_progress.styles import showtime

showtime()

Você verá um resultado semelhante ao seguinte.

O Alive-progress tem a capacidade de exibir e gerenciar várias barras de progresso simultaneamente.

from alive_progress import alive_bar
import time
import threading

# Simulate a task
def simulate_task(name, total):
    with alive_bar(total, title=name) as bar:
        for _ in range(total):
            # Do something
            time.sleep(0.5)

            bar()

# Define threads
threads = [
    threading.Thread(target=simulate_task, args=('Task A', 50)),
    threading.Thread(target=simulate_task, args=('Task B', 70)),
    threading.Thread(target=simulate_task, args=('Task C', 40)),
]

# Start each thread
for t in threads:
    t.start()

# Block the main thread until the program is finished
for t in threads:
    t.join()

A biblioteca alive-progress inclui vários temas incorporados. Os temas controlam elementos como o estilo de animação, os caracteres usados para preencher a barra e o efeito geral do movimento. Os temas comuns incluem classic, pulse e brackets.

import time
from alive_progress import alive_bar

with alive_bar(100, bar='blocks') as bar:
    for _ in range(100):
        # Do something
        time.sleep(0.02)
        
        bar()

Pausa/retomada - interrompe temporariamente e retoma o progresso sem perder o estado

from alive_progress import alive_bar
import time

# Run a task...
with alive_bar(100) as bar:
    for i in range(50):
        # Do something
        time.sleep(0.02)

        bar()
    
    # Pause
    bar.text('Temporarily pausing...')
    time.sleep(1)

    # Resume
    bar.text('Resuming...')
    for i in range(50):
        time.sleep(0.02)
        bar()

Barras de progresso da GUI com o Tkinter

Tkinter é o kit de ferramentas GUI (Graphical User Interface) padrão do Python. O design inclui recursos incorporados e está pronto para uso, portanto você não precisa instalar nada extra. Você pode criar janelas, botões, campos de texto, menus, barras de progresso e muito mais. O Tkinter é ideal para criar aplicativos de desktop simples, ferramentas interativas e protótipos. 

Uma barra de progresso básica pode ser criada usando o seguinte código. 

import tkinter as tk
from tkinter import ttk
import time

def start_progress():
    progress["value"] = 0
    root.update_idletasks()
    for i in range(101):
        time.sleep(0.02)
        progress["value"] = i
        root.update_idletasks()

# Set up the window
root = tk.Tk()
root.title("Progress Bar")
root.geometry("300x100")

# Create a progress bar
progress = ttk.Progressbar(root, orient="horizontal", length=250, mode="determinate")
progress.pack(pady=20)

# Create a start button
start_button = ttk.Button(root, text="Start", command=start_progress)
start_button.pack()

# Start the tkinter loop
root.mainloop()

Saída no meu Mac:

Há dois modos disponíveis no ttk.Progressbar: determinado e indeterminado. O modo determinado é usado quando a duração ou o número de etapas em uma tarefa é conhecido. O modo indeterminado é usado quando a duração da tarefa é desconhecida ou não pode ser medida em etapas.

O código acima é para um modo determinado, pois sabíamos que a duração da tarefa era de 250 etapas. A seguir, um exemplo de um modo indeterminado.

import tkinter as tk
from tkinter import ttk
import time
import threading

def start_indeterminate():
    def run():
        # 10 ms between moves
        progress.start(10)

        # Simulate task of unknown duration
        time.sleep(10)

        # Stop
        progress.stop()
    
    # Run in a thread, else the tkinter GUI loop is unresponsive
    threading.Thread(target=run).start()

# Set up the GUI
root = tk.Tk()
root.title("Indeterminate Progress Bar")
root.geometry("300x100")

# Create an indeterminate progress bar
progress = ttk.Progressbar(root, mode='indeterminate', length=250)
progress.pack(pady=20)

# Start button
start_button = ttk.Button(root, text="Start", command=start_indeterminate)
start_button.pack()

# Run the tkinter loop
root.mainloop()

Observe que a barra de progresso foi executada em um thread separado. Se usássemos o run() diretamente na thread principal, a chamada time.sleep() bloquearia o loop de eventos principal do Tkinter e faria com que toda a GUI congelasse, inclusive os cliques nos botões, o redesenho da janela e a animação da barra de progresso.

Considerações sobre desempenho e otimização

Qual biblioteca você deve usar para a barra de progresso? Parte da decisão depende de seus requisitos de sobrecarga e do seu caso de uso.

Para melhorar o desempenho, otimize a frequência de atualização. Um método é não atualizar a barra a cada iteração. Isso é especialmente importante em loops rápidos ou de alta frequência. Use a lógica condicional para atualizar a cada N etapas, por exemplo, a cada 100 iterações.

Nas configurações de desempenho crítico ou no código de produção, desative as barras de progresso. O feedback visual não é necessário aqui. Isso economiza recursos e garante que a lógica permaneça a mesma para desenvolvimento ou depuração. 

A redução das operações de E/S é fundamental para o desempenho. A gravação no terminal, no disco ou na rede pode deixar tudo mais lento. Aqui estão algumas estratégias para reduzir a E/S em tarefas críticas para o desempenho.

• Armazene a saída em buffer e grave em lotes em vez de por iteração.
• Atualize somente em intervalos fixos ou sob condições específicas.
• Minimizar ou desativar print() dentro de loops.
• Adicione sinalizadores para suprimir a saída desnecessária na produção.
• Separe a E/S e a computação usando threads ou multiprocessamento.
• Comprimir ou agrupar gravações grandes para reduzir a frequência de E/S do disco.

Práticas recomendadas para barras de progresso eficazes

Vamos dar uma olhada em algumas das práticas recomendadas que você deve ter em mente ao criar barras de progresso em Python. 

Por que usar barras de progresso?

Há muitos bons motivos para você usar barras de progresso em seus aplicativos. Primeiro, eles fornecem feedback em tempo real, assegurando aos usuários que as tarefas estão progredindo e reduzindo a incerteza. Essa visibilidade aprimora a experiência do usuário, fazendo com que os tempos de espera pareçam mais curtos e as interações mais intuitivas. 

Em segundo lugar, ao acompanhar visualmente a conclusão da tarefa, as barras de progresso permitem o monitoramento fácil do desempenho, possibilitando que os usuários e os desenvolvedores identifiquem rapidamente gargalos ou processos paralisados durante operações de longa duração. Por fim, a incorporação de barras de progresso eleva o profissionalismo da interface do seu aplicativo, transmitindo clareza e uma abordagem de design atenciosa e centrada no usuário.

Tarefas de duração conhecida versus desconhecida

Use uma determinada barra de progresso para tarefas que tenham um tempo definido. Isso inclui processamento de arquivos, loops ou épocas de treinamento de machine learning. Esse tipo de barra é preenchido com base no progresso mensurável e dá aos usuários uma noção clara de quanto trabalho ainda resta.

Para tarefas com duração desconhecida, como chamadas de API ou verificações em segundo plano, use um botão giratório ou uma barra indeterminada. Eles oferecem uma indicação visual de que o processo está em andamento, mesmo que não possamos prever quanto tempo levará.

Qual biblioteca devo usar?

A biblioteca A biblioteca que você usa depende das tarefas que você está tentando realizar.

Personalização

Ao personalizar as barras de progresso, concentre-se na clareza e nas informações úteis. Procure obter um bom equilíbrio entre os dois. Uma barra clara e simples com as principais métricas geralmente é melhor do que uma barra cheia de informações demais. 

Você pode usar bibliotecas como progressbar2 e alive-progress. Eles permitem que você altere o layout, a cor e a animação das barras de progresso. Usar temas ou formatação para melhorar a experiência do usuário. Evite sobrecarregar a tela com muitos widgets ou recursos visuais complexos. O objetivo é fornecer feedback útil. Queremos evitar distrair o usuário ou fazer com que ele se sinta sobrecarregado.

Tratamento de exceções e testes de compatibilidade

Envolva a lógica da barra de progresso em blocos try-except. Isso ajuda a evitar falhas na interface do usuário ou travamentos se ocorrer um erro durante uma tarefa. Isso é fundamental em scripts que são executados por um longo período ou quando você usa dependências externas incertas.

Além disso, teste suas barras de progresso em diferentes ambientes. Verifique em vários sistemas operacionais, tipos de terminais e larguras de tela. Dessa forma, você pode garantir que o comportamento deles permaneça consistente.

Algumas bibliotecas se comportam de forma diferente em notebooks Jupyter, terminais remotos ou shells de GUI. Verificar a compatibilidade com antecedência pode ajudar a evitar problemas inesperados. Dessa forma, os usuários terão uma experiência mais tranquila na produção.

Considerações sobre acessibilidade

Ao criar indicadores de progresso, considere a acessibilidade. Isso ajuda todos os usuários a receber um feedback claro. Algumas sugestões:

• Não dependa apenas de cores ou animações para mostrar o progresso. Adicione elementos de texto como porcentagens, contagem de passos ou estimativas de tempo.
• Use recursos visuais claros e de alto contraste para melhorar a legibilidade.
• Certifique-se de que suas barras de progresso funcionem bem com leitores de tela em aplicativos GUI.
• Para ferramentas de linha de comando, considere as opções de verbosidade que imprimem atualizações de progresso em texto simples.

Fazer da acessibilidade uma prioridade aumenta a usabilidade. Isso também torna suas ferramentas mais inclusivas e profissionais.

Conclusão 

As barras de progresso são um recurso simples, mas forte, para qualquer aplicativo Python. Eles fornecem feedback instantâneo, melhoram a experiência do usuário e acompanham o desempenho e a clareza do código. A escolha da biblioteca de barras de progresso correta é fundamental. Ele pode aprimorar seu software, quer você esteja criando um script rápido, uma ferramenta de linha de comando ou um aplicativo completo de GUI. Uma implementação bem pensada pode aumentar a velocidade, o profissionalismo e a facilidade de uso do seu software. Ao priorizar a personalização, o desempenho, a compatibilidade e a acessibilidade, você torna as barras de progresso mais do que meros recursos visuais. Eles se tornam uma parte importante de como os usuários se envolvem com o seu trabalho.

Para continuar aprendendo, confira estes recursos:

• Tqdm Python: Um guia com exemplos práticos 
• Introdução à GUI com Tkinter em Python 
• Fundamentos de programação Python