GX-TXT Python Script Workspace: eseguire uno Script dalla scheda Analysis
Uno Script Python registrato nella Session può essere eseguito anche dalla normale interfaccia Analysis di GX-TXT, senza aprire lo Script Runner. In questo percorso si configurano Script source mode, Session registered script, Working directory, Required GX-TXT APIs e gli eventuali Dataset di ingresso, poi si avvia il calcolo dalla scheda Run. La guida illustra un esperimento sintetico con cinque temperature, due revisioni dello Script e i rapporti di esecuzione originali.
1. Quando utilizzare il modulo Python Script in Analysis
Il Python Script Workspace serve alla scrittura, alla registrazione e alla manutenzione del codice. Il modulo Python Script presente in Analysis, invece, permette di eseguire uno Script della Session attraverso il normale ciclo di calcolo GX-TXT. È lo stesso codice registrato, ma con una modalità di selezione e una presentazione diverse: il modulo usa la configurazione scientifica dell’esperimento e produce un rapporto di esecuzione.
2. Abilitare Python Script nella configurazione
Se il modulo non è attivo, aprire Configuration → Modules, cercare Python Script e scegliere Enable module. Nell’elenco la voce mostra il proprio stato, ad esempio CORE / ON, e la versione installata. L’abilitazione rende disponibile il modulo alla Session; non esegue Python e non crea Dataset. Verificare separatamente la selezione Run / recalculate now.

3. La Session deve essere quella corretta
Prima di selezionare il programma, controllare quale Session è aperta. Lo Script di Analysis deve avere una registrazione Session valida, non un percorso di file arbitrario. Anche i Dataset da utilizzare devono appartenere alla Session corrente. L’identificativo qualificato dello Script consente a GX-TXT di ritrovare sorgente, versione, revisione e API richieste.
4. Creare uno Script dimostrativo nell’editor
Aprire il Python Script Workspace e utilizzare File → New Script. L’esempio legge cinque temperature sintetiche da un Dataset canonico: 18,0, 20,0, 22,5, 21,0 e 19,0 °C. Le misura non sono dati sperimentali, ma valori scelti per il tutorial. Il programma calcola la media aritmetica, che in questo caso è 20,1 °C.

5. Dichiarare l’API numerica di accesso ai Dataset
Lo Script si basa sul Python Script Client pubblico e usa CANONICAL_DATASET_API_v2, senza chiamare funzioni private del framework. Una dichiarazione esplicita delle API richieste consente al Registry di riconoscere i prerequisiti dello Script prima dell’esecuzione:
from gxtxt import gxtxt_context, gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
La dichiarazione viene riconosciuta staticamente da GX-TXT: non avvia il calcolo e non apre il Dataset.
6. Salvare e registrare lo Script della Session
Inserire Script ID, Name, Version e Scope appropriati, quindi scegliere File → Save. Il Registry conserva il sorgente Python, la revisione, lo SHA-256 e le API necessarie. La scheda dell’editor indica che il file è stato salvato. In seguito, se si cambia il codice, il normale salvataggio registra una nuova revisione dello stesso Script.

7. Selezionare il modulo dalla scheda Analysis
Aprire Analysis e individuare il riquadro Python Script. Il modulo ha una propria casella Run / recalculate now e una sezione Calculation configuration. In una Session con numerosi moduli è possibile nascondere temporaneamente i pannelli non pertinenti dalla scheda Modules, senza disabilitare i loro servizi o eliminare i risultati precedenti.
8. Scegliere Script source mode
Il campo Script source mode indica come GX-TXT individua il programma. Nel modulo Python installato viene utilizzata la modalità registered_script, cioè una sorgente già presente nel Registry della Session. Non sostituire il riferimento registrato con un percorso di file esterno: il percorso e l’identità dello Script non sono equivalenti.
9. La scelta Session registered script
La combobox Session registered script elenca le sorgenti Python registrate nella Session. Selezionando lo Script previsto, la descrizione mostra lingua, ID, nome, versione, revisione e SHA-256. Controllare questi dati prima di procedere: l’identità visibile permette di distinguere due revisioni dello stesso programma e impedisce di confondere una scheda editor con la sorgente eseguibile selezionata.

10. Required GX-TXT APIs viene sincronizzato
La selezione dello Script può compilare automaticamente Required GX-TXT APIs (semicolon-separated) usando le dichiarazioni salvate nel Registry. Per il nostro esempio compare CANONICAL_DATASET_API_v2@2. Non è necessario ricopiare manualmente una lista di API già dichiarate nel sorgente; il contratto effettivo deve essere verificato con la revisione registrata corrente.
11. Working directory: una directory di esecuzione
Working directory (optional) imposta la directory di lavoro della procedura. Se viene specificata, deve essere una posizione ammessa e coerente con la Session e con gli strumenti di analisi. Non confonderla con la cartella del sorgente, con il Dataset canonico o con l’output_dir gestita dal Job. L’output_dir è la destinazione supervisionata in cui l’esecuzione scrive rapporto e file temporanei.
12. La tabella Dataset sources
La sezione Dataset sources (Analysis Source Map API v1) associa un identificativo semantico a un Dataset canonico. Nell’esempio l’ingresso usa Source ID: primary, selezionando un Dataset numerico già registrato. La scelta è effettuata mediante la combobox originale, non scrivendo direttamente percorsi fisici del CSV. Il Dataset può trovarsi nel namespace di un modulo diverso dal namespace corrente della Session.

13. Source ID e Dataset ID non sono intercambiabili
primary è il nome logico assegnato all’ingresso del programma. Il Dataset ID identifica invece il contenuto canonico della Session. Nel nostro caso sono presenti le variabili sample_index e temperature_c. Il collegamento rende disponibile al Job un riferimento controllato al Dataset, senza cambiare il suo produttore, il suo contenuto o il namespace della Session.
14. Recuperare l’ingresso tramite gxtxt_context
Durante l’esecuzione reale il contesto pubblico Python espone il Dataset associato all’alias:
context = gxtxt_context()
primary = context["inputs"]["primary"]
dataset_id = primary["dataset_id"]
info = gxtxt_api_call(
"CANONICAL_DATASET_API_v2", "describe", [dataset_id]
)
Il codice usa l’identificativo ricevuto dal CORE e non presuppone un nome di file né una posizione sul disco. È la Session a controllare quale Dataset corrisponde a quell’ID.
15. Leggere le temperature con Canonical Dataset API v2
Per acquisire la variabile scientifica richiesta si può utilizzare l’operazione pubblica read_range. Si specificano Dataset ID, Variable ID e intervallo delle righe:
block = gxtxt_api_call(
"CANONICAL_DATASET_API_v2",
"read_range",
[dataset_id, ["temperature_c"], 0, int(info["row_count"])]
)
Il risultato espone valori e tipo della variabile secondo il contratto canonico. Non è necessario usare direttamente il parser CSV o interpretare a mano i metadati della Session.
16. Gestire correttamente gli scalari NumPy
Alcuni valori provenienti dal trasporto scientifico possono essere rappresentati da array NumPy con un solo elemento. Convertire direttamente un array non scalare con float(array) può generare avvisi di deprecazione. Una conversione esplicita consente di usare valori numerici Python mantenendo un comportamento chiaro:
samples = [
float(value.item() if hasattr(value, "item") else value)
for value in block["temperature_c"]["values"]
]
if len(samples) != 5:
raise ValueError("Expected five synthetic samples")
mean_c = sum(samples) / len(samples)
print(f"Synthetic mean: {mean_c:.1f} degC")
L’esempio controlla anche il numero di campioni, anziché assumere che la selezione abbia sempre la forma desiderata.
17. Il rapporto e l’output_dir del Job
Il contesto contiene anche output_dir, la directory gestita dal framework per i file della singola esecuzione. È possibile scrivervi un testo riassuntivo:
from pathlib import Path
Path(context["output_dir"]).joinpath("summary.txt").write_text(
f"Mean: {mean_c:.1f} degC\n", encoding="utf-8"
)
Un file scritto nel Job non è automaticamente un Dataset canonico. La pubblicazione scientifica richiede un’API di registrazione dedicata, illustrata nei capitoli relativi agli output.
18. Preparare il comando nella scheda Run
Dopo avere verificato Script e Dataset, aprire Run. Il comando principale è Run enabled analyses. La pagina contiene anche Execution plan, che dovrebbe riepilogare i moduli selezionati e gli ingressi. Non usare indiscriminatamente Run: accertarsi che i moduli richiesti siano gli unici selezionati e che la Session sia quella corretta.
19. Una limitazione dell’Execution plan
Nella versione descritta, il prospetto Execution plan può non elencare Python Script anche quando il modulo è abilitato, visibile e selezionato per l’elaborazione. Può quindi indicare erroneamente che nessun modulo è pronto. È una discrepanza della presentazione del piano: l’azione Run enabled analyses mantiene il proprio percorso di esecuzione. Prima di usarla, verificare direttamente le scelte nella scheda Analysis e non interpretare lo zero del prospetto come prova che lo Script sia inattivo.

20. Avviare l’analisi Python
Premere Run enabled analyses dopo aver controllato la configurazione. GX-TXT prepara il runtime del modulo e avvia la procedura attraverso il proprio supervisore. Durante l’esecuzione la pagina Run presenta il modulo attivo e uno stato come Python Script — Running…. Non è necessario aprire il Python Script Runner e non occorre passare attraverso la Script Library.

21. La conclusione viene confermata da GX-TXT
Quando il calcolo termina correttamente, lo stato della pagina Run e una finestra informativa indicano che l’analisi selettiva è completata. Queste informazioni attestano la chiusura del percorso Analysis, ma la verifica scientifica deve esaminare anche il rapporto, il sorgente e il contenuto dell’output.

22. Leggere il risultato dell’esempio
Il programma ha letto le cinque temperature dal Dataset canonico e stampato la media 20,1 °C, coerente con i valori sintetici di input. Ha confermato anche la directory di lavoro configurata. Nessun nuovo Dataset numerico è stato pubblicato da questa procedura: il calcolo è stato registrato come Job con rapporto e file di output del runtime.
23. Il file python_script_run_report.txt
Il modulo produce un rapporto Python contenente informazioni come stato PASS, linguaggio, modulo, versione, modalità registered_script, riferimento e revisione dello Script, SHA-256 atteso e verificato, runtime Python, API richieste e identificativo della singola esecuzione. Questi campi aiutano a stabilire che il Job ha utilizzato la sorgente prevista.
24. executed_script.py è una copia congelata
La copia executed_script.py conserva il codice effettivamente eseguito. Non va confusa con il sorgente correntemente aperto nell’editor, che potrebbe essere stato modificato in seguito. Una revisione successiva dello Script mantiene il precedente Job e la sua copia di esecuzione: la provenienza scientifica rimane distinta e verificabile.
25. Correggere una conversione senza cambiare i dati
Se il programma genera un avviso legato alla rappresentazione di uno scalare NumPy, modificarne la conversione nell’editor Python, lasciando invariati il Dataset di origine, le API richieste e l’algoritmo della media. Usare il normale File → Save per registrare la sorgente corretta. Non alterare manualmente il contenuto delle copie congelate nei Job precedenti.

26. La revisione 2 mantiene la provenienza della revisione 1
Salvando il codice corretto, il Registry assegna una nuova revisione e un nuovo SHA-256 al medesimo Script. Il primo Job conserva la revisione precedente, mentre la nuova esecuzione utilizzerà il sorgente aggiornato. Questo è il vantaggio di lavorare con Script registrati: le revisioni sono esplicite e non cancellano la storia dell’esperimento.

27. Ripetere il calcolo dalla pagina Run
Con lo Script aggiornato, tornare alla scheda Run e ripetere l’esecuzione selettiva del modulo Python. Il nuovo Job utilizza la revisione 2, legge lo stesso Dataset e restituisce ancora 20,1 °C, senza l’avviso precedente. Il rapporto originale registra la nuova revisione e il nuovo SHA-256. Il prospetto Execution plan può continuare a omettere il modulo, benché lo stato finale riporti Selective analysis completed.


28. Tornare al Workspace e verificare la Session
Dopo avere esaminato rapporto, dati e provenienza, chiudere eventuali finestre di esecuzione e tornare al Python Script Workspace. In High Contrast Dark è possibile riprendere la modifica dei sorgenti. Il modulo Analysis e il Runner rimangono strumenti distinti, basati sullo stesso Registry e sulle API scientifiche pubbliche; lo sviluppo successivo riguarderà gli strumenti di debugging, con nuove procedure autonome.
