Barre di avanzamento in Python: guida completa con esempi

Nelle app di oggi, gli utenti vogliono un feedback immediato, soprattutto quando i task richiedono tempo. Le barre di avanzamento in Python sono un modo chiaro e semplice per mostrare che qualcosa sta succedendo in background. Una buona barra di avanzamento fa sembrare il programma più rapido, aggiunge un tocco professionale e migliora la facilità d’uso. 

In questo articolo imparerai a implementare barre di avanzamento in Python usando librerie popolari come tqdm, progress, progressbar2, alive-progress e Tkinter, insieme alle best practice per migliorare l’esperienza utente e le prestazioni dell’applicazione.

Per imparare concetti di Python in modo pratico, dai un’occhiata al nostro percorso di competenze Python Programming Fundamentals. 

TL;DR

• Per gli strumenti da riga di comando, tqdm è la scelta di riferimento — è leggero e funziona bene con pandas. Usa progress per script semplici, progressbar2 quando ti servono layout personalizzati o alive-progress per visuali animate.

• Per le app desktop, il ttk.Progressbar integrato di Tkinter gestisce sia i task a durata nota (determinati) sia quelli aperti (indeterminati).

• Limita la frequenza degli aggiornamenti nei loop veloci per evitare rallentamenti e abbina le visuali a testi come percentuali o conteggi, così la barra resta utile per tutti.

Cosa sono le barre di avanzamento in Python?

Le barre di avanzamento sono ovunque. Sono spesso usate per download di file, installazioni software ed pipeline ETL. Sono utili anche per monitorare l’addestramento dei modelli di machine learning.

La barra di avanzamento mostra quanto di un task è stato completato e quanto resta. Può apparire come testo in un’interfaccia a riga di comando (CLI) o come barra visiva in un’interfaccia grafica (GUI).

Le barre di avanzamento migliorano l’esperienza utente. Forniscono aggiornamenti in tempo reale, mostrando agli utenti a che punto sono nel processo. Se c’è un ritardo, possono decidere se intervenire o aspettare. Questa visibilità riduce la frustrazione e fa percepire i tempi di attesa come più brevi. Gli utenti non fissano uno schermo statico chiedendosi se stia succedendo qualcosa: restano coinvolti e rassicurati che c’è progresso.

Gli sviluppatori usano le barre di avanzamento per monitorare le prestazioni delle applicazioni. Aiutano a individuare colli di bottiglia, fare benchmark del codice e tracciare la durata dei task. Nello scripting e nei workflow mostrano aggiornamenti di stato chiari, aiutando a comprendere meglio i processi di lunga durata. Migliorano anche l’usabilità di strumenti interattivi e notebook.

Le barre di avanzamento possono fungere anche da semplice monitoraggio delle prestazioni. Mostrano quanto tempo impiega ciascun task. Questo aiuta gli sviluppatori a individuare fasi lente e a misurare l’efficienza, consentendo un confronto agevole tra implementazioni. 

Barre di avanzamento da riga di comando

Le barre di avanzamento da riga di comando forniscono un feedback visivo per i task di lunga durata direttamente nel terminale, rendendo gli script più informativi e user-friendly. Python offre diverse librerie, ciascuna con punti di forza in velocità, personalizzazione e stile visivo. Vedremo quattro opzioni: tqdm, progress, progressbar2 e alive-progress. 

Tqdm: lo standard per velocità e semplicità

tqdm è una libreria molto diffusa in Python per creare barre di avanzamento. Fornisce indicatori rapidi e versatili per loop e iterabili. Tiene traccia delle iterazioni e calcola sia il tempo rimanente sia quello trascorso, aggiornando la barra in tempo reale. tqdm lavora in background, stima quanto tempo resta ed evita aggiornamenti non necessari. È semplice da imparare, usa poca memoria ed è supportata da una community solida. 

Installazione

Un modo semplice per installare tqdm è usare l’installer pip. Digita il seguente comando nel terminale.

pip install tqdm

Stampa il numero di versione per assicurarti che la libreria sia installata correttamente.

import tqdm
print(tqdm.__version__)

4.67.1

Uso di base di tqdm

tqdm è semplice da usare. Importa la libreria. Avvolgi qualsiasi iterabile con tqdm(iterable) per visualizzare una barra di avanzamento.

Invece di scrivere tqdm(range(n)), puoi usare la scorciatoia trange(n) per comodità.

from tqdm import trange
import time

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

Questo codice produce una barra di avanzamento live durante l’esecuzione.

La barra di avanzamento mostra

• Percentuale completata (22%)
• Numero di iterazioni completate sul totale (224/1000)
• Tempo trascorso e tempo rimanente stimato (12 secondi trascorsi, 42 secondi rimanenti)
• Iterazioni al secondo (18,09 it/s).

Per aggiungere una descrizione alla barra, specifica l’opzione desc.

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

Barre di avanzamento annidate 

Le barre di avanzamento annidate in tqdm aiutano a tracciare il progresso su più loop. Sono utili anche quando devi monitorare più fasi di lavoro. Esempi includono elaborazioni a batch, loop annidati e training di modelli. 

Avvolgi ogni loop con tqdm. Usa gli argomenti position e leave per controllarne l’aspetto.

• position: imposta la posizione verticale di ogni barra. position=0 è la barra in alto, position=1 appare sotto, e così via.
• leave: se leave=True, la barra resta a schermo dopo la fine. Se leave=False, scompare per evitare ingombro.

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)

Le barre annidate mostrano una gerarchia chiara. Ti aiutano a visualizzare le diverse fasi di un task e offrono dettagli a vari livelli, facilitando l’individuazione di rallentamenti o colli di bottiglia.

Integrazione con pandas

Tqdm si integra bene con pandas. Fornisce un modo semplice per aggiungere barre di avanzamento a task su DataFrame e Series. Mostra il progresso in tempo reale per funzioni come apply, groupby e map, che con dataset grandi possono essere lente.

Per abilitare la funzione, chiama tqdm.pandas(). Poi usa progress_apply invece del normale apply di pandas. Comparirà una barra che mostra l’avanzamento della funzione su righe o colonne. Vedrai il progresso dell’operazione senza riscrivere il codice.

Nel programma seguente creiamo un DataFrame con una colonna chiamata "numbers" che contiene interi da 0 a 1000. Generiamo quindi una nuova colonna applicando un’operazione "lenta" chiamata slow_squared. 

Invece di usare la funzione standard apply di pandas, usiamo progress_apply di tqdm. Durante l’operazione compare una barra che fornisce aggiornamenti in tempo reale su quanto è stato elaborato.

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())

L’output del codice è il seguente.

Possiamo usare progress_apply anche per altre operazioni sul DataFrame come groupby.

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

Opzioni di personalizzazione

Tqdm ti permette di personalizzare le barre per adattarle a vari ambienti ed esigenze. Puoi regolare la larghezza con ncols. L’argomento bar_format ti dà pieno controllo sul layout del testo. Inoltre, impostando dynamic_ncols=True la barra si ridimensiona automaticamente in base al terminale.

Considerazioni sulle prestazioni specifiche di tqdm

Tqdm è rapido e leggero. Aggiunge poco overhead anche nei loop veloci. Puoi disabilitare le barre con disable=True, utile in produzione quando le prestazioni sono cruciali. Nei loop molto rapidi, aggiornare la barra a ogni iterazione può essere eccessivo: tqdm ti consente di controllare la frequenza di aggiornamento con parametri come mininterval e maxinterval. 

Progress: stili personalizzabili e spinner

La libreria Progress in Python permette di creare semplici barre di avanzamento testuali per la riga di comando. Ha un’API lineare, supporta sia barre sia spinner e consente una personalizzazione basilare dell’output. È piccola, veloce e senza dipendenze: perfetta per script rapidi e setup semplici. 

La libreria progress include sette stili integrati di barre: Bar, ChargingBar, FillingSquaresBar, FillingCirclesBar, IncrementalBar, PixelBar e Shadybar. 

Per l’installazione, usa pip.

pip install progress

Per usarla, importa lo stile desiderato, istanzia una variabile, usa .next() nel loop e .finish() al termine del processo. Ad esempio, per usare una ChargingBar, ecco il codice.

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 include anche spinner per task a durata sconosciuta. Il codice per implementare uno spinner è lineare.

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()

Questo codice mostra la descrizione ("Processing…") seguita da uno spinner.

La libreria progress è semplice e leggera, ma ha alcune limitazioni: non supporta i notebook Jupyter, non può ridimensionarsi dinamicamente e offre meno opzioni di personalizzazione rispetto a librerie come tqdm. Funziona bene per task basilari da CLI, ma può faticare con lavori complessi o ad alte prestazioni.

Progressbar2: personalizzazione avanzata e compatibilità

Progressbar2 è una potente libreria Python che aiuta a creare barre di avanzamento flessibili e personalizzabili per app da riga di comando. Offre molti widget, come percentuale, ETA, marker animati e contatori, ideale per task CLI più complessi o curati. 

Progressbar2 offre più controllo e formattazione rispetto a librerie più semplici come progress. Inoltre, si integra meglio con logging e workflow multithread.

Per installarla, usa pip.

pip install progressbar2

La classe ProgressBar in progressbar2 mostra lo stato corrente dell’avanzamento tramite un set di widget personalizzabili. 

Un widget è una parte modulare che si aggiorna in base allo stato della barra: percentuale completata, tempo trascorso e tempo rimanente stimato. 

Puoi scegliere tra molti tipi di widget: etichette testuali, marker di avanzamento, contatori, timer, spinner e formattatori personalizzati. Questa varietà ti permette di adattare aspetto e funzionalità della barra alla tua app.

L’uso di base di Progressbar2 è piuttosto semplice. 

import time
import progressbar

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

L’output mostra percentuale completata, iterazioni completate/iterazioni totali, tempo trascorso e tempo rimanente stimato.

Le librerie per barre di avanzamento in genere aggiornano una singola riga nel terminale usando il carriage return (\r). Questo significa che le normali istruzioni print() possono interferire spingendo la barra in basso o corrompendone l’output. La libreria progressbar2 offre un modo sicuro per stampare messaggi senza interferire con la barra.

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)

La libreria progressbar2 offre un’ampia personalizzazione tramite il suo sistema modulare di widget. I widget mostrano dettagli come percentuale completata, tempo trascorso, tempo rimanente stimato, contatori o animazioni della barra. Puoi combinarli per creare una barra su misura. Per esempio, puoi mostrare percentuale ed ETA, oppure aggiungere dettagli come nomi file, timestamp o spinner. 

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: animazioni dinamiche per terminal moderni

Alive-progress mostra barre animate che cambiano in tempo reale, dando alle app da riga di comando un aspetto moderno e reattivo. La barra avanza e mostra metriche utili in tempo reale: percentuale, tempo trascorso, tempo rimanente stimato e velocità di iterazione. È quindi sia gradevole sia informativa.

Per installare la libreria alive-progress, usa pip.

pip install alive-progress

Come mostrato sulla sua pagina GitHub, per vedere una demo delle sue capacità, usa il seguente codice.

from alive_progress.styles import showtime

showtime()

Vedrai un output simile al seguente.

Alive-progress può mostrare e gestire più barre di avanzamento contemporaneamente.

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()

La libreria alive-progress include diversi temi integrati. I temi controllano elementi come lo stile dell’animazione, i caratteri usati per riempire la barra e l’effetto di movimento complessivo. Tra i temi comuni ci sono 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/ripresa — interrompi temporaneamente e riprendi l’avanzamento senza perdere lo stato

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()

Barre di avanzamento GUI con Tkinter

Tkinter è il toolkit GUI (Graphical User Interface) standard di Python. Ha funzionalità integrate ed è pronto all’uso, quindi non serve installare altro. Puoi creare finestre, pulsanti, campi di testo, menu, barre di avanzamento e altro. Tkinter è ideale per costruire semplici applicazioni desktop, strumenti interattivi e prototipi. 

Una barra di avanzamento di base può essere creata con il seguente codice. 

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()

Output sul mio Mac:

Sono disponibili due modalità con ttk.Progressbar: determinata e indeterminata. La modalità determinata si usa quando la durata o il numero di step di un task è noto. Quella indeterminata si usa quando la durata è sconosciuta o non può essere misurata in step.

Il codice sopra è per la modalità determinata, dato che sapevamo che il task durava 250 step. Un esempio di modalità indeterminata segue.

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()

Nota che la barra è stata eseguita in un thread separato. Se usassimo run() direttamente nel thread principale, la chiamata time.sleep() bloccherebbe il loop eventi principale di Tkinter e congelerebbe l’intera GUI, inclusi click sui pulsanti, ridisegno della finestra e animazione della barra.

Considerazioni sulle prestazioni e ottimizzazione

Quale libreria dovresti usare per la tua barra di avanzamento? In parte la decisione dipende dai requisiti di overhead e dal caso d’uso.

Per migliorare le prestazioni, ottimizza la frequenza degli aggiornamenti. Un metodo è non aggiornare la barra a ogni iterazione, soprattutto nei loop veloci o ad alta frequenza. Usa logica condizionale per aggiornare ogni N step, ad esempio ogni 100 iterazioni.

In contesti critici per le prestazioni o in produzione, disabilita le barre. Qui il feedback visivo non è necessario. Risparmi risorse mantenendo la stessa logica usata in sviluppo o debugging. 

Ridurre le operazioni di I/O è fondamentale per le prestazioni. Scrivere su terminale, disco o rete può rallentare. Ecco alcune strategie per ridurre l’I/O in task critici per le prestazioni.

• Bufferizza l’output e scrivi a blocchi invece che per iterazione.
• Aggiorna solo a intervalli fissi o sotto condizioni specifiche.
• Riduci al minimo o disattiva print() nei loop.
• Aggiungi flag per sopprimere output non necessari in produzione.
• Separa I/O e computazione usando thread o multiprocessing.
• Comprimi o raggruppa scritture corpose per ridurre la frequenza di I/O su disco.

Best practice per barre di avanzamento efficaci

Vediamo alcune best practice da tenere a mente quando crei barre di avanzamento in Python. 

Perché usare le barre di avanzamento?

Ci sono molti buoni motivi per usare le barre di avanzamento nelle tue applicazioni. Anzitutto forniscono un feedback in tempo reale, rassicurando gli utenti che i task stanno procedendo e riducendo l’incertezza. Questa visibilità migliora la UX, fa percepire più brevi i tempi di attesa e rende le interazioni più intuitive. 

Inoltre, tracciando visivamente il completamento dei task, le barre consentono un monitoraggio prestazionale semplice, permettendo a utenti e sviluppatori di individuare rapidamente colli di bottiglia o processi bloccati durante operazioni di lunga durata. Infine, integrare barre di avanzamento eleva la professionalità dell’interfaccia, comunicando chiarezza e un design attento all’utente.

Task a durata nota vs sconosciuta

Usa una barra determinata per i task con durata definita: elaborazione di file, loop o epoche di training. Questo tipo di barra si riempie in base al progresso misurabile e dà un’idea chiara di quanto lavoro resta.

Per task a durata ignota, come chiamate API o controlli in background, usa uno spinner o una barra indeterminata. Offrono un indizio visivo che il processo è in corso, anche se non possiamo prevedere quanto durerà.

Quale libreria dovrei usare?

La libreria che usi dipende dai task che stai cercando di svolgere.

Personalizzazione

Quando personalizzi le barre, punta a chiarezza e informazioni utili, bilanciandole bene. Una barra semplice e chiara con metriche chiave è di solito migliore di una piena di elementi.

Puoi usare librerie come progressbar2 e alive-progress per modificare layout, colori e animazioni. Usa temi o formattazioni per migliorare l’esperienza. Evita di affollare la visualizzazione con troppi widget o elementi complessi: l’obiettivo è fornire un feedback utile senza distrarre o sovraccaricare l’utente.

Gestione delle eccezioni e test di compatibilità

Racchiudi la logica delle barre in blocchi try-except. Aiuta a evitare glitch grafici o crash se si verifica un errore durante un task. È fondamentale per script di lunga durata o quando si usano dipendenze esterne incerte.

Inoltre, testa le barre in ambienti diversi: sistemi operativi, tipi di terminale e larghezze di display differenti, per assicurarti che il comportamento resti coerente.

Alcune librerie si comportano in modo diverso nei notebook Jupyter, nei terminali remoti o nelle shell GUI. Verificare la compatibilità in anticipo aiuta a prevenire problemi imprevisti e garantisce un’esperienza più fluida in produzione.

Considerazioni di accessibilità

Quando crei indicatori di avanzamento, considera l’accessibilità per garantire un feedback chiaro a tutti. Alcuni suggerimenti:

• Non affidarti solo a colore o animazione. Aggiungi testo come percentuali, conteggio step o stime di tempo.
• Usa visuali chiare e con buon contrasto per una migliore leggibilità.
• Assicurati che le barre funzionino bene con gli screen reader nelle app GUI.
• Per gli strumenti da riga di comando, valuta opzioni di verbosità che stampino aggiornamenti in testo semplice.

Dare priorità all’accessibilità migliora l’usabilità e rende i tuoi strumenti più inclusivi e professionali.

Conclusione 

Le barre di avanzamento sono una funzionalità semplice ma potente per qualsiasi app Python. Offrono feedback immediato, migliorano l’esperienza utente e aiutano a monitorare prestazioni e chiarezza del codice. Scegliere la libreria giusta è fondamentale: può valorizzare il tuo software, che si tratti di uno script rapido, di uno strumento da riga di comando o di una GUI completa. Un’implementazione attenta può migliorare velocità, professionalità e facilità d’uso. Dare priorità a personalizzazione, prestazioni, compatibilità e accessibilità rende le barre più di semplici elementi visivi: diventano parte cruciale dell’interazione con il tuo lavoro.

Per continuare a imparare, esplora queste risorse:

• Tqdm Python: guida con esempi pratici 
• Introduzione alla GUI con Tkinter in Python 
• Python Programming Fundamentals