GX-TXT Python Script Workspace: dal sorgente al risultato scientifico
Una guida conclusiva per verificare un lavoro Python prima di archiviarlo, condividerlo o riutilizzarlo: controllo del sorgente, input e parametri, esecuzione, output, Dataset canonici e debugger. Le immagini mostrano le stesse funzioni esaminate nei capitoli precedenti.
1. Che cosa deve essere riproducibile
Un calcolo scientifico è riproducibile quando si possono ricostruire l’identità dei dati di ingresso, la versione esatta del programma, i parametri effettivi, l’esecuzione e il risultato. Nel Python Script Workspace di GX-TXT questi elementi non coincidono: Script o Project, Job, Dataset e Session hanno ruoli distinti. Il log del programma e il Dataset canonico non sono intercambiabili.
2. Scegliere correttamente Session e Scope
Un sorgente di scope User è distinto da quello collegato a una Session, anche quando presenta lo stesso nome breve. Le esecuzioni scientifiche descritte qui richiedono la Session appropriata e un sorgente registrato. Prima di salvare o eseguire verificare lo scope visualizzato nella GUI. Non attribuire automaticamente a una Session dati provenienti da un’altra.
3. Controllare l’editor e lo stato del sorgente
Usare Python Script Workspace con un’area di codice ampia. Il tema High Contrast Dark rende riconoscibili testo Python, selezione e riga corrente; le barre e i dialoghi nativi possono conservare il loro aspetto chiaro. Prima di iniziare un Job, assicurarsi che non ci siano modifiche pendenti e che il file mostrato corrisponda alla versione salvata.

4. Identità, versione, revisione e SHA
Stable ID identifica uno Script o Project nel relativo scope; la Version semantica è una descrizione della sua evoluzione; la revision del Registry identifica uno specifico salvataggio. L’impronta SHA-256 consente di verificare che il contenuto realmente eseguito coincida con il sorgente salvato. Nei Project multifile la revisione rappresenta un insieme coerente di file, non un unico .py arbitrario.
5. Salvare prima di eseguire
Scegliere File → Save per uno Script singolo o File → Save All per un Project con più file. Il salvataggio non crea automaticamente un Job e non produce un Dataset. Dopo una modifica, ripetere il salvataggio e verificare la nuova revisione; l’eventuale Job precedente conserva il suo snapshot storico e non cambia retroattivamente.
6. Collegare un Dataset e conservarne la revisione
In Script Runner, la sezione Inputs and output permette di usare Add input Dataset. Controllare namespace, Dataset ID, alias semantico, etichetta e revisione. L’alias è il nome con cui il codice ritrova il Dataset, mentre l’ID canonico ne identifica la registrazione. Se il Dataset sorgente viene aggiornato dopo la selezione, Validate review può richiedere una nuova selezione della revisione corrente.

7. Dichiarare e rivedere i parametri tipizzati
Un parametro dichiarato con gxtxt_parameter_declare può avere tipo, valore predefinito, limiti e descrizione. Nel Runner si sceglie il valore effettivo per la singola invocazione. Cambiare un parametro nel Runner non equivale a modificare il sorgente. Se sono presenti valori manuali, controllare anche eventuali conflitti con i parametri dichiarati nel programma.

8. I confini delle API Python pubbliche
Il client pubblico gxtxt permette al codice di ottenere il contesto del Job e chiamare le API disponibili. Ad esempio, nell’esercitazione W02 è stata usata questa sequenza essenziale:
from gxtxt import gxtxt_api_call, gxtxt_api_require, gxtxt_context
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
context = gxtxt_context()
dataset_id = context["inputs"]["measured"]["dataset_id"]
metadata = gxtxt_api_call(
"CANONICAL_DATASET_API_v2", "describe", [dataset_id]
)
gxtxt_api_require verifica la dipendenza dall’API richiesta; gxtxt_context dà accesso a input e parametri della specifica esecuzione; describe legge lo schema del Dataset. Le operazioni di lettura, calcolo e pubblicazione rimangono separate. Non usare moduli interni del CORE come scorciatoie.
9. Validate review non è Run Job
Il pulsante Validate review controlla la configurazione. Un messaggio come Review valid. No Job submitted non significa che il programma sia stato eseguito. Prima di premere Run Job ricontrollare la revisione dello Script, la Session, gli input, i parametri e l’eventuale ID di output. Questa distinzione impedisce di confondere una configurazione ammissibile con un risultato già ottenuto.

10. Controllare lo stato terminale del Job
Dopo Run Job, aprire Script Jobs Manager. Un Job QUEUED o RUNNING non è concluso; un Job COMPLETED con exit code zero segnala la conclusione normale; FAILED e CANCELLED hanno significati diversi. Verificare sempre l’identità e la revisione eseguita, non limitarsi a leggere l’ultima riga di output.
11. Separare stdout, stderr e diagnostica
In Job Details scegliere il flusso adatto: Program output contiene i messaggi scritti su stdout, Program stderr raccoglie i messaggi del processo su stderr, mentre i log diagnostici sono informazioni di esecuzione distinte. Per un Job con flussi lunghi, le pagine visualizzate non sono l’intero contenuto: i comandi di copia/esportazione completa sono separati dalle funzioni che selezionano soltanto la pagina corrente.

12. Primo controllo scientifico: Celsius e kelvin
Nell’esercitazione W01 il programma ha elaborato cinque temperature sintetiche 18, 20, 22, 21, 19 °C applicando K = °C + 273.15. I cinque valori in kelvin sono 291,15, 293,15, 295,15, 294,15 e 292,15. La media aritmetica è 293,15 K. Il Job definitivo ha terminato con successo e lo stdout conserva tutte le righe del calcolo.

13. Secondo controllo scientifico: calibrazione additiva
Nell’esercitazione W02 un Dataset canonico di temperature 18, 20, 22.5, 21, 19 °C è stato letto tramite CANONICAL_DATASET_API_v2. Il parametro tipizzato correction_degC era impostato a +0,75 °C. Il calcolo ha prodotto 18,75, 20,75, 23,25, 21,75 e 19,75 °C, con media 20,85 °C. Questi numeri derivano da dati didattici sintetici, non da misure strumentali.

14. Il Dataset scientifico non nasce dal solo print
print() scrive nel log, ma non crea una tabella canonica. W02 ha pubblicato esplicitamente un Dataset table.generic con due variabili, raw_c e corrected_c, entrambe di tipo float64 e unità degC. Il processo di pubblicazione usa DATASET_PUBLICATION_API_v2, con apertura del writer, dichiarazione di dimensione e variabili, aggiunta dei valori e finalizzazione. La provenienza conserva il collegamento al Dataset iniziale.
15. Verificare l’output richiesto e quello pubblicato
L’Output Dataset ID del Runner identifica una richiesta, non la certezza di una pubblicazione. In Job Details distinguere Requested output e Committed published Datasets. Un Job può terminare normalmente senza pubblicare un Dataset, se lo Script non effettua una finalizzazione. Prima di riutilizzare il risultato rileggere schema, righe, tipi, unità e valori dal catalogo canonico.

16. Project Python: ingresso, helper e revisione unica
Nel lavoro W03 main.py importava calibrate da helpers/numeric.py, mentre helpers/__init__.py identificava il package. Le letture sintetiche [1, 4, 9], moltiplicate per due, hanno restituito [2, 8, 18] e la somma 28. L’intero Project è stato salvato con Save All; il Job ha conservato lo snapshot di tutti e tre i file. Un controllo del solo main.py non sarebbe sufficiente per certificare il calcolo.
17. Breakpoint e Call Stack: il punto di esecuzione è unico
Nel debugger nativo il tasto F9 inserisce un breakpoint eseguibile nel file desiderato. Start Debug, Continue, Step Into, Step Over e Step Out controllano la vera esecuzione del Job Python. Call Stack permette di selezionare un frame chiamante e osservare altri valori locali, senza cambiare la posizione dell’interprete. Le schede dei file helper sono quindi parte della normale navigazione del Project.

18. Pause, Stop e sicurezza dell’esecuzione
Durante RUNNING, il comando Pause può sospendere un Job Python; la conferma è lo stato effettivo PAUSED, non il solo click. La prova W03 ha raggiunto controlled_spin alla riga 12; il successivo Stop ha prodotto CANCELLED. Il caso è distinto dal Job scientifico completato con somma 28. Se il margine dei breakpoint rimane disabilitato dopo la chiusura del debugger, chiudere e riaprire il Project tramite i normali menu: il contenuto salvato viene conservato.

19. Controlli prima di condividere il lavoro
Prima di archiviare o condividere una procedura, verificare che il sorgente sia salvato e privo di modifiche pendenti; che il Project includa tutti i file richiesti; che Session, input, alias, parametri e revisioni siano quelli voluti; che il Job abbia lo stato appropriato; che stderr e log siano stati consultati; e, quando è previsto un Dataset, che il risultato sia stato realmente pubblicato e riletto con tipo, unità e provenienza corretti. La presenza di una schermata rassicurante non sostituisce questi controlli.
20. Percorso di studio e limite delle esercitazioni
I capitoli P01–P14 spiegano l’interfaccia, l’editor, i Project e le note; P15–P20 trattano Runner, Dataset, parametri e Jobs; P21–P24 il debugger; P25–P29 cronologia, output, pubblicazioni e assistenza. W01–W03 mostrano le tre esercitazioni scientifiche complete. Tutti gli esempi numerici di questa serie sono sintetici: non dimostrano l’accuratezza metrologica di strumenti reali e non sostituiscono una valutazione delle incertezze sperimentali.