GX-TXT Python Script Workspace: dichiarare parametri nel sorgente e configurarli nel Runner
In Python Script Workspace i parametri di un programma possono essere dichiarati direttamente nel sorgente con gxtxt_parameter_declare(), definiti nei metadati dello Script oppure aggiunti per una singola invocazione tramite Script Runner. Questa guida spiega i tre livelli, i tipi consentiti, i limiti e il controllo delle revisioni. La sola dichiarazione, il salvataggio o la validazione dei parametri non esegue Python e non avvia un Job.
1. Perché dichiarare i parametri
In un programma scientifico i coefficienti, il numero di ripetizioni e le modalità di elaborazione non dovrebbero essere numeri nascosti nel codice. Dichiararli in modo esplicito rende più chiaro il contratto fra lo Script e la sua futura invocazione. GX-TXT permette di descrivere nome, tipo, obbligatorietà, valore predefinito e vincoli, mantenendo l’identità dei parametri accanto alla revisione dello Script registrato.
2. Tre livelli da distinguere
I parametri del sorgente sono dichiarazioni gxtxt_parameter_declare() nel file Python. I parametri dei metadati sono definiti nell’editor, nella tabella Typed parameters. I parametri manuali di invocazione vengono invece aggiunti e rimossi nella sola finestra Script Runner. I primi due appartengono allo schema salvato; il terzo livello vale per la revisione corrente della richiesta e non riscrive il Registry.
3. Aprire lo Script Python nella Session corretta
Nel Python Script Workspace aprire la Session desiderata e scegliere uno Script registrato, oppure utilizzare File → New Script per prepararne uno. Compilare Scope, Script ID, Name e Version e poi inserire il sorgente. La Session è il contesto scientifico della futura esecuzione; il semplice editing non produce né un Dataset numerico né un risultato di Job.
4. La funzione pubblica gxtxt_parameter_declare
La dichiarazione Python utilizza due argomenti posizionali letterali, nome e tipo, seguiti da argomenti opzionali per nome, anch’essi letterali. Per esempio:
from gxtxt import gxtxt_parameter_declare
gxtxt_parameter_declare(
"gain", "double",
default=1.5, min=0.5, max=3.0,
description="Synthetic calibration gain"
)
Non si tratta di un comando che avvia il calcolo: la dichiarazione viene riconosciuta staticamente durante il salvataggio dello Script.
5. Un esempio Python con tre parametri
Questo frammento illustra tre proprietà differenti: un coefficiente numerico, un numero intero di ripetizioni e una modalità scelta da un elenco.
from gxtxt import gxtxt_parameter_declare, gxtxt_context
gxtxt_parameter_declare(
"gain", "double", default=1.5,
min=0.5, max=3.0, description="Synthetic gain"
)
gxtxt_parameter_declare(
"replicates", "integer", required=True,
default=3, min=1, max=9,
description="Number of readings"
)
gxtxt_parameter_declare(
"mode", "choice", default="linear",
values=["linear", "offset"],
description="Conversion mode"
)
I commenti e le descrizioni del codice sono in inglese; il testo della guida spiega il significato di ciascuna istruzione.

6. I tipi disponibili
I tipi supportati dallo schema sono string, integer, double, number, boolean, choice, color, path, file e command. Usare un tipo coerente con la semantica del valore: integer per un conteggio, double per un coefficiente e choice quando l’utente deve selezionare una delle opzioni enumerate. La scelta del tipo controlla anche il campo visualizzato dal Runner.
7. required e default
L’opzione required=True dichiara l’obbligatorietà del parametro. default fornisce invece il valore proposto inizialmente dal Runner. Un parametro può avere entrambe le proprietà: per esempio, replicates è obbligatorio ma inizialmente valorizzato a 3. Se si elimina un valore richiesto senza una sostituzione valida, il controllo dell’invocazione deve segnalare il problema.
8. I limiti min e max
Per i tipi numerici integer, double e number è possibile dichiarare un minimo e un massimo. La coppia min=0.5, max=3.0 stabilisce l’intervallo ammesso per gain. Il valore predefinito deve rientrarvi, il minimo non può superare il massimo e i vincoli numerici devono essere finiti. Questi controlli proteggono la preparazione dell’invocazione, non dimostrano la validità scientifica del modello.
9. I parametri di tipo choice
Per il tipo choice, values contiene un elenco letterale di stringhe ammesse, per esempio ["linear", "offset"]. Il valore default deve appartenere all’elenco e le alternative non devono essere duplicate. Il Runner presenta una scelta fra le opzioni ammesse invece di un campo numerico libero. Non costruire le alternative mediante una funzione o una variabile calcolata all’interno della dichiarazione.
10. Il ruolo di description
description è una breve spiegazione del parametro, mostrata per aiutare l’utente a compilare il Runner. Per un coefficiente o una misura è opportuno esplicitare il significato fisico e le eventuali unità nella descrizione, se pertinenti. Il testo descrittivo non costituisce uno schema di unità del Dataset: le unità dei dati canonici appartengono alle rispettive variabili scientifiche.
11. Salvare lo Script e analizzare le dichiarazioni
Premere File → Save. Durante il salvataggio, GX-TXT analizza staticamente il testo Python e registra le dichiarazioni valide nello schema dello Script. Il parser non esegue le istruzioni scientifiche, gli import o le espressioni presenti nel programma. Se le dichiarazioni non rispettano la sintassi prevista, il salvataggio viene rifiutato anziché inserire silenziosamente uno schema incompleto.

12. Revisione, origine e tracciabilità
Le dichiarazioni provenienti dal sorgente vengono registrate con l’origine source e informazioni di provenienza come il nome del file, il numero di riga e lo SHA-256 corrispondente al sorgente salvato. Una modifica del codice richiede una nuova revisione registrata e una nuova verifica prima di un Job. Non si deve confondere l’impronta del sorgente con i valori compilati in una singola invocazione.
13. La tabella Typed parameters dell’editor
L’editor include anche Typed parameters, con righe nel formato name | type | required | default | description. Queste righe appartengono ai metadati registrati, non sono dichiarazioni inserite nel codice. Un esempio indipendente è:
operator | string | 0 | lab | Optional tutorial operator
Il campo required usa la rappresentazione 0/1. La tabella non richiede di aggiungere una funzione Python con lo stesso nome.
14. Combinare sorgente e metadati
I parametri dichiarati nel file Python e quelli aggiunti tramite la tabella dell’editor possono essere combinati quando hanno nomi distinti. Nell’esempio lo Script registrato possiede quattro parametri: gain, replicates e mode provengono dal sorgente, mentre operator è un parametro editoriale. L’origine diversa rimane significativa anche se tutti e quattro vengono presentati nello stesso Runner.
15. Evitare dichiarazioni duplicate
Non dichiarare lo stesso nome due volte nel sorgente e non riutilizzare per una dichiarazione un nome già presente nei metadati. Il parser rifiuta duplicati e conflitti: non sceglie arbitrariamente quale definizione mantenere. Per correggere la situazione è necessario modificare la dichiarazione o il parametro editoriale, quindi salvare nuovamente. La mera apertura dello Script Runner non corregge i conflitti del Registry.
16. Aprire il Runner sui parametri salvati
Con lo Script registrato e non modificato, usare Run → Open Script Runner…. La finestra mostra nome, versione, revisione e SHA-256 dello Script, seguiti dagli ingressi tipizzati. Nell’esempio compaiono gain (double), mode (choice), operator (string) e replicates (integer). Il valore predefinito e l’indicazione required o optional provengono dallo schema salvato.

17. Modificare un valore e usare Validate review
I valori mostrati nel Runner possono essere corretti prima dell’esecuzione. Se gain ammette al massimo 3,0 e si inserisce 9,0, Validate review segnala che il valore supera il limite. Il controllo esamina l’invocazione senza lanciare Python. Un messaggio come Review needs attention richiede una correzione prima di considerare valida la richiesta.

18. Tornare a un valore accettato
Sostituendo 9,0 con un valore ammesso, per esempio 1,75, e ripetendo Validate review, il Runner può indicare Review valid. No Job submitted. Questo significa soltanto che i controlli attuali dell’invocazione hanno avuto successo. Non certifica la correttezza scientifica dei risultati futuri e non equivale a premere Run Job.
19. Additional parameters for this invocation
Il Runner dispone di una sezione Additional parameters for this invocation, indipendente dai parametri salvati. Premendo Add parameter… si può definire un valore ulteriore, utile per una specifica elaborazione. La nuova definizione viene aggiunta alla sola revisione locale dell’invocazione e non viene automaticamente registrata nel sorgente o nella tabella dei metadati dello Script.
20. Il dialogo Add invocation parameter
La finestra di aggiunta permette di compilare Name, Type, Value, Required, Description, Choices (Tcl list), Minimum e Maximum, con i pulsanti Apply e Cancel. Il tipo determina le opzioni rilevanti: per esempio, Minimum e Maximum sono vincoli numerici. Cancel chiude il dialogo lasciando invariato lo schema dell’invocazione.

21. Il nome manuale non può duplicare un nome salvato
Se si tenta di aggiungere un parametro manuale chiamato gain, già definito nel sorgente registrato, la finestra rifiuta Apply. Il messaggio indica che il nome coincide con una dichiarazione salvata. Occorre scegliere un identificativo distinto, per esempio offset, invece di creare due valori concorrenti con lo stesso nome semantico.

22. Anche i limiti del parametro manuale vengono controllati
Un parametro offset di tipo double non può essere dichiarato con Minimum = 4,0 e Maximum = 2,0. Il pulsante Apply lascia il dialogo aperto e mostra che il minimo supera il massimo. Impostare invece limiti coerenti con il problema scientifico, per esempio da −2,0 a 2,0, quindi verificare che il valore iniziale sia interno all’intervallo.

23. Aggiungere un offset valido
Impostare Name = offset, Type = double, Value = 0.25, Minimum = -2.0 e Maximum = 2.0; l’eventuale Required e la Description completano la definizione. Dopo Apply, la riga offset (double) compare nella sezione dei parametri aggiuntivi, con i pulsanti Edit e Remove. Lo Script registrato mantiene la propria revisione e lo stesso SHA-256.

24. Validare lo schema effettivo dell’invocazione
Durante la revisione il Runner combina i parametri salvati con quelli aggiunti per l’invocazione. Validate review controlla il risultato tipizzato e i relativi limiti, rifiutando nomi in conflitto o valori non validi. Nell’esempio l’invocazione contiene i quattro parametri registrati e offset, ma nessun parametro aggiunto manualmente viene scritto nel Registry. Il parametro non diventa un Dataset solo perché viene inserito nel Runner.
25. Modificare un parametro manuale con Edit
Il pulsante Edit riapre la definizione del parametro aggiunto, permettendo di cambiarne il valore e gli eventuali vincoli. Per esempio, offset può passare da 0,25 a 0,5. Dopo Apply, la riga aggiornata viene validata senza risalvare il sorgente. Distinguere questa modifica locale da una nuova revisione del programma Python.

26. Eliminare un parametro manuale con Remove
Il pulsante Remove della riga aggiuntiva elimina quel parametro dalla richiesta corrente. Non cancella le dichiarazioni nel sorgente e non modifica i parametri già registrati. Nell’esempio, rimosso offset, rimangono gain, mode, operator e replicates. Se occorre modificare permanentemente un parametro proveniente dal sorgente, intervenire invece nella dichiarazione e salvare lo Script.

27. Errori nelle dichiarazioni e conflitti durante Save
GX-TXT richiede che nome, tipo e vincoli delle dichiarazioni siano letterali; non valuta una variabile o una funzione per ricavarne il valore. Il salvataggio rifiuta inoltre dichiarazioni duplicate, valori predefiniti fuori dai limiti, scelte non comprese nelle alternative e import con alias non supportati. Se si aggiunge nel sorgente una dichiarazione operator quando operator esiste già nei metadati, File → Save mostra Save failed e non aggiorna la revisione registrata. Correggere il sorgente e riprovare.

28. Dove leggere i valori effettivi e come proseguire
Durante un’esecuzione effettiva, lo Script può leggere i valori tipizzati mediante gxtxt_context()["parameters"]. La dichiarazione gxtxt_parameter_declare() è invece un marcatore statico e non restituisce in fase di editing il valore dell’invocazione. Il contesto di esecuzione rende disponibile anche lo schema dei parametri; prima di un Job rimangono indispensabili la verifica di Session, sorgente, input e valori.
Terminata la revisione, scegliere Close per ritornare all’editor Python High Contrast Dark. Il prossimo capitolo tratterà il salvataggio e caricamento dei Parameter Dataset; l’invio con Run Job resterà una procedura separata.
