2.41. Debugging¶

La maggior parte degli script che falliscono sulla camera fallisce in uno di tre modi: sollevano un’eccezione, producono un valore errato oppure si bloccano. Ognuno richiede un diverso insieme di strumenti.

2.41.1. Leggere un traceback¶

Quando uno script solleva un’eccezione e nessuno la gestisce, il REPL o l’IDE stampa un traceback – una traccia della catena di chiamate, dallo script più esterno fino alla riga che ha sollevato l’eccezione.

Un traceback si legge dal basso verso l’alto:

La riga in fondo indica la classe dell’eccezione e il suo messaggio (ValueError: invalid literal for int()...).
Ogni blocco File "...", line N, in <name> sopra di essa è un frame – una chiamata più in profondità man mano che si sale.
Il frame in cima è il punto in cui lo script è iniziato; il frame in fondo è il punto in cui l’errore si è verificato.

Leggi prima la riga in fondo per capire cosa è andato storto, poi risali per vedere come lo script è arrivato lì. I numeri di riga indicano le posizioni esatte nel sorgente dello script.

2.41.2. Debugging con print¶

Il modo più rapido per scoprire cosa sta facendo uno script è stampare i valori sospetti. Tre funzioni integrate rendono le stampe più utili:

repr() – restituisce la rappresentazione testuale in stile sviluppatore di un valore. print(repr(value)) distingue "5" da 5 e None da "None", cosa che un semplice print() non può fare.
type() – restituisce la classe di un valore. print(type(value)) è il modo per scoprire se la variabile che «dovrebbe essere un int» è in realtà una stringa.
len() – la lunghezza di una sequenza o di una collezione. Una frazione sorprendentemente grande dei bug sono problemi di off-by-one o di dimensioni non corrispondenti.

print("got:", repr(value), "type:", type(value), "len:", len(value))

Inserisci una print all’interno di ogni ramo che ti interessa – entrambi i rami di un if, ogni blocco except, il corpo di un ciclo che sospetti venga eseguito zero volte. Il costo è una riga di output; il valore è scoprire se il percorso di codice che pensi venga eseguito è davvero quello che viene eseguito.

2.41.3. Esplorare un oggetto¶

Due funzioni integrate rispondono alla domanda «cosa posso fare con questa cosa»:

dir() – restituisce un elenco di ogni nome definito su un oggetto: metodi, attributi, dunder, tutto quanto.
help() – stampa la docstring (e, su CPython, la firma) di una funzione, un metodo o una classe.

Usale insieme: dir trova il nome, help spiega cosa fa.

2.41.3.1. Trovare un nome con dir¶

>>> dir([1, 2, 3])
['__add__', '__class__', '__contains__', '__delitem__',
 '__eq__', '__ge__', ..., 'append', 'clear', 'copy',
 'count', 'extend', 'index', 'insert', 'pop', 'remove',
 'reverse', 'sort']

La prima parte dell’elenco è composta dai metodi dunder, ereditati da ogni oggetto; i nomi che vale la pena cercare di solito vengono dopo di essi. dir funziona su qualsiasi cosa – una classe, un’istanza, un modulo, un tipo integrato:

>>> import json
>>> dir(json)
['__name__', 'dump', 'dumps', 'load', 'loads']

Quella seconda forma è il modo per scoprire quali nomi di livello superiore un modulo espone effettivamente senza uscire dal REPL.

2.41.3.2. Consultarlo con help¶

Una volta che dir ha fatto emergere un candidato, help lo descrive:

>>> help(str.split)
split(sep=None, maxsplit=-1)
    Return a list of the words in the string, ...

Su MicroPython, help è più essenziale che su CPython – a volte solo la firma, a volte una docstring di una riga, a volte nulla per le funzioni C integrate. È comunque un rapido promemoria quando il tooltip dell’IDE non è a portata di mano.

2.41.4. Quando qualcosa si blocca¶

Uno script che non restituisce il controllo è più difficile da diagnosticare di uno che solleva un’eccezione. Cause comuni:

Un ciclo while la cui condizione non diventa mai falsa. Aggiungi una print della variabile del ciclo a ogni iterazione; se il valore non cambia, il corpo del ciclo ha un bug.
Una chiamata bloccante in attesa di un input che non arriva mai – una lettura da una coda vuota, una sleep senza fine. Circonda la chiamata con delle print per vedere su quale riga lo script è bloccato.
Una ricorsione infinita. Il traceback che alla fine si verifica (con RecursionError) di solito la indica con precisione.

Il recupero più efficace per uno script bloccato è il pulsante stop dell’IDE, che invia un KeyboardInterrupt allo script tramite USB. L’interrupt emerge come un traceback alla riga attualmente in esecuzione – spesso esattamente la riga che non restituisce il controllo.

Nota

Se un blocco resiste a ogni diagnosi – lo script sembra corretto, il traceback dell’interrupt punta a una funzione integrata o al codice del firmware anziché al tuo script, oppure lo stesso codice funzionava su una build precedente del firmware – la causa potrebbe essere un bug del firmware anziché un bug dello script. Riduci lo script al più piccolo esempio riproducibile che continua a bloccarsi e apri una segnalazione sul forum di OpenMV. Includi la versione del firmware, la scheda su cui è stato eseguito e lo script ridotto.

2.41.5. Rimuovi le diagnostiche prima della distribuzione¶

Le print strategiche durante lo sviluppo sono ottime; cento chiamate a print lasciate in uno script di produzione ingombrano l’output e usano heap che il lavoro reale potrebbe usare. Quando un bug è risolto, rimuovi le print (oppure proteggile dietro un flag di debug che puoi disattivare).

Per le diagnostiche che devono rimanere nel percorso di codice a lungo termine, passa da print() al modulo logging. Esso associa un livello a ogni messaggio (debug, info, warning, error) e consente a una singola impostazione di silenziare quelli meno importanti in produzione:

import logging

log = logging.getLogger("main")
log.info("starting up")
log.debug("loaded config: %s", config)
log.warning("falling back to defaults")

Impostare il livello del logger su logging.WARNING rende le chiamate info e debug praticamente a costo zero (la stringa del messaggio non viene mai costruita), senza dover commentare le righe. Questo rende logging lo strumento giusto per le diagnostiche permanenti; la print grezza va bene per quelle usa e getta.