Eccezioni e sicurezza delle chiamate API
Corso Python scientifico in GX-TXT · Modulo 1 · Lezione 6
Un programma incontra situazioni inattese: un valore non ha il tipo previsto, manca una chiave o una richiesta a un’API non è valida. Python usa le eccezioni per segnalare queste condizioni. Impareremo a riconoscerle e a gestire un errore intenzionale del bridge pubblico di GX-TXT senza farlo passare per un risultato scientifico valido.
Obiettivi: distinguere errori di sintassi e di
esecuzione; comprendere try, except,
else e finally; verificare una API e
interpretare un GXTXTBridgeError.
Prerequisiti: funzioni, dizionari e client pubblico incontrati nelle lezioni 1–5.
Che cos’è un’eccezione
Un’eccezione interrompe il normale flusso di esecuzione e trasporta informazioni sull’errore. Se nessun gestore la intercetta, Python termina il programma e mostra un traceback, cioè la sequenza delle chiamate che ha portato al problema. Leggi il messaggio e la riga pertinente: non sono una diagnosi scientifica, ma aiutano a individuare dove iniziare.
SyntaxError segnala codice che Python non riesce a
interpretare, come una parentesi mancante. TypeError può
indicare un’operazione fra tipi incompatibili, per esempio
"volume " + 2.5. KeyError può indicare una
chiave richiesta ma assente, come abbiamo visto nella lezione 5. In
generale, un try nello stesso file non può intercettare un
errore che impedisce a Python di analizzare quel file: prima bisogna
correggere la sintassi.
try ed except
try:
valore = int("quattro")
except ValueError as errore:
print("Conversione non valida:", errore)
Python esegue il blocco indentato sotto try. La
conversione fallisce con ValueError; il gestore
corrispondente riceve l’eccezione nel nome errore. Se tutto
procede senza eccezioni, il blocco except viene saltato. Se
si verifica un’eccezione di un altro tipo, questo gestore non la
intercetta.
Cattura l’eccezione che sai interpretare e fornisci un messaggio
utile. Usare indiscriminatamente except Exception per
stampare «successo» nasconde i problemi. Se il dato è indispensabile per
un calcolo, interrompi il lavoro o segnala chiaramente il fallimento;
non sostituire silenziosamente il valore mancante con zero.
else e finally
Un blocco else dopo except viene eseguito
se il blocco try termina senza eccezioni.
finally viene eseguito quando si lascia il costrutto, sia
nel caso normale sia quando si verifica un’eccezione gestita o
propagata; è utile per un’operazione di chiusura necessaria. Non usare
finally per cancellare o mascherare un errore: in alcune
interruzioni esterne, come la terminazione forzata del processo, Python
potrebbe non avere occasione di eseguirlo.
try:
numero = int("4")
except ValueError:
print("Testo non convertibile")
else:
print("Valore letto:", numero)
finally:
print("Tentativo terminato")
Qui il testo è valido e l’output include Valore letto: 4
e Tentativo terminato. Le condizioni if e i
flussi più articolati saranno trattati nel prossimo modulo.
Controllare le API pubbliche
gxtxt_api_has(api_id) chiede se l’API è registrata nel
bridge corrente e restituisce un valore logico.
gxtxt_api_require richiede una dichiarazione, ad esempio
CANONICAL_DATASET_API_v2@2, che specifica l’API e la
versione richiesta. Questi controlli riguardano la disponibilità
dichiarata: non garantiscono che gli argomenti siano scientificamente
validi o che una risorsa esterna sia pronta.
gxtxt_api_call(api_id, operazione, argomenti) richiama
un’operazione pubblica. Quando la richiesta al bridge è rifiutata, il
client può sollevare GXTXTBridgeError, con un
identificativo e un messaggio. Nell’esempio richiediamo
intenzionalmente un’operazione inesistente su un’API
disponibile, per osservare la risposta: non stiamo cercando di calcolare
o modificare dati. L’errore atteso è
GXTXT:ScriptBridge:UnknownOperation; messaggio e dettagli
possono variare fra versioni.
Codice completo
from gxtxt import gxtxt_api_has, gxtxt_api_require, gxtxt_api_call, GXTXTBridgeError
api = "CANONICAL_DATASET_API_v2"
print("API disponibile:", api, gxtxt_api_has(api))
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
print("Requisito soddisfatto")
operazione = "operazione_inesistente"
try:
gxtxt_api_call(api, operazione, [])
except GXTXTBridgeError as errore:
print("Errore intenzionale intercettato:", errore)
else:
print("La richiesta inattesa non ha generato un errore")
finally:
print("Controllo concluso")
La lista vuota [] è l’elenco degli argomenti della
chiamata dimostrativa; non rappresenta un Dataset. Il nome
dell’operazione è volutamente inesistente: l’eccezione viene mostrata e
il programma prosegue fino a finally. Se il requisito
iniziale dell’API non è soddisfatto, l’esercizio non deve essere
interpretato come riuscito.

Il controllo della disponibilità e la chiamata intenzionalmente errata nell’editor.
Esegui e leggi l’output
- Apri una Session e il Viewer Python Scripts.
- Importa
eccezioni_api.py, assegna uno Script ID nello scopesessione salva. - Apri Run → Open Script Runner…, premi Run Job e attendi il completamento.
- Nell’output cerca il valore booleano della disponibilità,
Requisito soddisfatto, l’errore intenzionale eControllo concluso.

Il bridge rifiuta l’operazione inesistente; il programma mostra l’errore atteso e conclude il controllo.
Distinguere i problemi
Un’API non registrata, un’operazione inesistente, argomenti non validi e una risorsa esterna non disponibile sono condizioni diverse. Il messaggio e l’identificativo aiutano a distinguerle; consulta la documentazione del descrittore prima di tentare una chiamata. Un’eccezione intercettata significa che il programma ha gestito una condizione, non che un’operazione scientifica sia stata eseguita con successo.
Esercizio
Un operatore inserisce il testo "2.5" come volume
sintetico in mL. Scrivi un blocco che lo converta con float
e mostri un messaggio chiaro se il testo non è numerico. Che cosa accade
con "due"?
Soluzione ragionata
testo = "2.5"
try:
volume_ml = float(testo)
except ValueError as errore:
print("Volume non convertibile:", errore)
else:
print("Volume sintetico (mL):", volume_ml)Con "2.5" viene mostrato 2.5; con
"due" la conversione solleva ValueError e
viene mostrato il messaggio. In una vera acquisizione servirebbero anche
controlli su intervallo, unità e incertezza: la sola conversione non
basta.
Hai completato i concetti di base del modulo. Nel prossimo modulo useremo condizioni, cicli e funzioni per organizzare meglio gli script.