GX-TXT Python Script Workspace: identità, versioni e metadati degli Script
Prima di eseguire un programma Python in GX-TXT è necessario distinguere il sorgente nell’editor dalla sua identità registrata. Il Workspace permette di attribuire uno Scope, uno Script ID, un Name, una Version, le API richieste, una Description e i parametri tipizzati. Queste proprietà servono a conservare e identificare il programma e a descriverne i futuri input. Non eseguono automaticamente un calcolo.
1. Una bozza non è ancora uno Script registrato
All’apertura di Python Script Workspace compare normalmente una scheda untitled.py. Si tratta di un documento modificabile, non di un risultato scientifico e non necessariamente di uno Script già presente nel Registry.
Uno Script registrato, invece, ha un ambito e un identificativo persistente, insieme ai metadati e a una revisione. Il suo codice è conservato separatamente dall’esecuzione di un Job e dall’eventuale pubblicazione di Dataset.
2. Dove si trovano i campi
Nella parte superiore del Viewer sono presenti Scope, Script ID e Name. Attraverso il menu View si possono mostrare o nascondere Version, Additional required APIs, Description e Typed parameters.
Aprire soltanto i pannelli utili all’attività corrente: in fase di scrittura, mantenere un’area di codice ampia favorisce la leggibilità. Quando occorre completare l’identità, è ragionevole rendere visibili temporaneamente i campi di registrazione.
3. Lo stato iniziale in una Session
Se una Session è aperta, una nuova bozza può assumere Scope = session, avere Name Untitled script e Version 1.0.0, mentre lo Script ID risulta vuoto.
L’assenza dell’ID è significativa: la scheda non contiene ancora una registrazione persistente. L’apertura dell’editor non genera né Script eseguibili né Dataset.

4. Scope user e Scope session
user identifica la raccolta degli Script dell’utente, utilizzabile per preparare un sorgente anche senza una Session aperta.
session individua invece una registrazione appartenente alla Session corrente. Se si intende conservare uno Script all’interno di uno specifico esperimento, occorre verificare di aver aperto la Session corretta prima di registrarlo.
5. Cambiare Scope non trasferisce uno Script
Lo Scope è una componente dell’identità dello Script, non un comando per spostare automaticamente un record fra raccolte. Modificare il campo in una bozza non equivale a copiare uno Script User nella Session.
Per creare un’identità differente sono previste operazioni esplicite di copia, assegnazione o salvataggio con altro identificativo. Non occorre utilizzarle durante la semplice preparazione dei metadati.
6. Script ID: un identificativo stabile
Script ID è la chiave tecnica del record. Nella versione illustrata deve iniziare con una lettera e può contenere lettere, numeri, underscore, punto e trattino.
Un ID con spazi o slash, oppure che inizi con un underscore, viene rifiutato dal validatore. È opportuno scegliere un identificativo compatto, significativo e non dipendente dal nome del computer o dalla posizione dei file.
7. Name: il titolo per il lettore
Name è il nome descrittivo mostrato nella GUI. Può essere più leggibile dell’identificativo tecnico: per esempio, Calibrazione sintetica: metadati.
Il Registry richiede un Name non vuoto. Questo titolo aiuta a riconoscere lo scopo dello Script nell’Explorer, ma non prende il posto dello Script ID.
8. Compilare i dati identificativi
Scegliere uno Scope, inserire uno Script ID valido e completare Name e Version. Se lo Script deve dichiarare dipendenze o ulteriori informazioni, mostrare dal menu View gli appositi campi.
L’immagine seguente presenta i metadati di un esempio sintetico. I campi sono stati compilati nell’editor; la modifica locale non è ancora una revisione registrata.

9. Il campo Version
Version richiede il formato numerico major.minor.patch, per esempio 1.2.0. Una versione con due soli componenti, una quarta componente o parole non numeriche non soddisfa il contratto di questa versione del Registry.
La versione semantica è scelta dall’autore. Può indicare la maturità o l’evoluzione logica dello Script, ma non conta automaticamente il numero di operazioni di salvataggio.
10. Il campo Description
Description descrive in breve la finalità dello Script, gli input attesi e il significato scientifico. Per esempio si può indicare che il sorgente è un esempio sintetico e non contiene misure strumentali.
Il metadato deve essere una sola riga. Non è codice Python, non viene eseguito e non sostituisce un’adeguata documentazione delle formule o delle unità adottate.
11. Additional required APIs
Il campo Additional required APIs consente di dichiarare dipendenze da interfacce pubbliche GX-TXT. Un identificativo documentato per il modulo numerico è NUMERIC_API_v1@1:math.numeric.
La dichiarazione non costituisce una chiamata all’API e non garantisce, da sola, che una specifica operazione sia disponibile nel runtime. Prima di eseguire uno Script bisogna consultare il contratto dell’API richiesta e verificare i prerequisiti effettivi.
12. Typed parameters: formato delle righe
Il pannello Typed parameters utilizza una riga per parametro, con cinque campi separati da una barra verticale:
name | type | required (0/1) | default | description
Il pannello raccoglie uno schema dei futuri argomenti. Scrivere queste righe non introduce istruzioni nel sorgente Python e non avvia un Job.

13. Un valore reale facoltativo
La prima riga dell’esempio è:
gain | double | 0 | 2.0 | Synthetic calibration gain
gain è il nome del parametro, double il tipo numerico reale, 0 il flag di facoltatività e 2.0 il valore predefinito dichiarato.
La descrizione ne chiarisce il ruolo. In un esperimento vero, per qualsiasi quantità dimensionale sarà opportuno esplicitare anche l’unità di misura e le convenzioni scientifiche.
14. Un parametro intero obbligatorio
La seconda dichiarazione è:
replicates | integer | 1 | | Required synthetic replicate count
Il tipo integer identifica un numero intero; il flag 1 dichiara che il parametro è richiesto. Il default è volutamente vuoto: non viene predisposto un numero di ripetizioni.
L’esempio riguarda soltanto lo schema. Il controllo dei valori effettivamente forniti a un Job avviene nella fase di preparazione dell’esecuzione.
15. Altri tipi supportati
Il Registry riconosce, oltre a double e integer, anche string, number, boolean, choice, color, path, file e command.
La scelta del tipo deve essere coerente con la funzione dello Script. La validazione dei metadati controlla la struttura e il tipo dichiarato; non certifica la plausibilità scientifica dei valori o la loro compatibilità con eventuali modelli fisici.
16. Che cosa significa required
Il campo required accetta un flag booleano, rappresentato normalmente da 0 o 1. Con 0 il parametro è facoltativo; con 1 viene dichiarato obbligatorio.
Obbligatorietà e default sono concetti differenti. Un parametro facoltativo può disporre di un valore predefinito, mentre un parametro obbligatorio può richiedere una scelta esplicita al momento dell’invocazione.
17. Controllare i parametri prima di Save
Prima di registrare lo Script, rileggere i nomi, i tipi, i flag e i default. Il validatore respinge dichiarazioni con nomi duplicati, tipi sconosciuti, flag required impropri o un numero non valido di campi.
Le regole sullo schema dei parametri proteggono la descrizione dello Script, ma non eseguono alcuna verifica sperimentale. L’eventuale validazione dei valori in fase di Job sarà oggetto di una procedura distinta.
18. I metadati modificano lo stato locale
Quando si cambia un campo identificativo o una riga di Typed parameters, il Workspace può segnalare modified.
Per una bozza non ancora registrata, la barra di stato mostra l’assenza dell’identità salvata e uno SHA-256 ancora in attesa. Il fatto che il testo Python sia rimasto identico non impedisce ai metadati di risultare modificati.
19. Registrare una prima versione
Con i metadati completati, File → Save registra lo Script nell’ambito scelto. Al record vengono associati Scope, ID, nome, versione, requisiti API, parametri e un riferimento al sorgente.
Dopo la prima registrazione, la barra mostra la revisione r1, il prefisso dell’impronta SHA-256 del codice e lo stato saved. La scheda può comparire con il nome source.py.

20. Revision e Version non sono la stessa cosa
La Version semantica è un valore deciso dall’autore, per esempio 1.2.0. La revision è invece il numero della revisione del record nel Registry.
Un nuovo salvataggio può incrementare revision anche se l’autore non cambia la Version. Viceversa, un campo Version cambiato nella bozza non modifica il Registry finché non viene salvato.
21. SHA-256 del codice: che cosa rappresenta
Lo SHA-256 mostrato nella barra identifica il contenuto sorgente registrato. Due revisioni con il medesimo codice possono conservare la stessa impronta del sorgente.
Il Registry possiede inoltre una propria informazione di integrità del record, che comprende i metadati e può variare quando questi vengono aggiornati. Non va confusa con lo SHA-256 del codice Python.
22. Modificare soltanto la Version
Supponiamo di passare da 1.2.0 a 1.2.1 senza cambiare il sorgente. Il campo Version mostra subito il nuovo valore, mentre la revisione salvata rimane temporaneamente r1.
La barra indica modified perché il buffer dei metadati non coincide più con l’ultima registrazione. La schermata permette di riconoscere immediatamente questa differenza.

23. Salvare la modifica dei soli metadati
Dopo il nuovo Save, il Registry passa a r2 e conserva Version 1.2.1. Nell’esempio il codice Python non è stato cambiato, quindi lo SHA-256 del sorgente rimane identico a quello di r1.
Questo dimostra perché revision non è un indice delle sole modifiche al codice. Una revisione può esistere anche per documentare un aggiornamento descrittivo.

24. Mettere a confronto le identità
| Proprietà | Prima registrazione | Metadati aggiornati |
|---|---|---|
| Version | 1.2.0 | 1.2.1 |
| Revision | r1 | r2 |
| Codice Python | Identico | Identico |
| SHA-256 del sorgente | Stesso valore | Stesso valore |
| Metadati del record | Prima versione | Versione aggiornata |
La tabella riguarda un esempio di sola variazione dei metadati. Quando si modificherà il codice e lo si registrerà di nuovo, il rapporto fra SHA e revisione potrà essere differente.
25. Consultare Registered Python scripts
Attraverso View → Script Explorer / Registered scripts si può aprire temporaneamente il pannello con gli Script registrati.
La lista presenta il Name e il riferimento dello Script, che per uno Script Session comprende il prefisso session:. Il pannello è utile per identificare ciò che è stato effettivamente registrato; non occorre tenerlo costantemente aperto durante la scrittura del codice.

26. Registrazione, esecuzione e Dataset restano separati
La registrazione dei metadati non esegue il sorgente. Anche la presenza di Additional required APIs o di parametri obbligatori non implica l’invio di un Job.
L’esecuzione richiede una procedura esplicita e i relativi controlli. Un Dataset scientifico viene pubblicato soltanto attraverso il percorso appropriato e non nasce automaticamente dal semplice Save di uno Script.
27. Errori comuni e limiti dell’identità
Un ID con caratteri non ammessi, una versione che non rispetta major.minor.patch o parametri duplicati devono essere corretti prima della registrazione. Un nome descrittivo non sostituisce uno Script ID valido.
Dopo la registrazione, modificare Scope o Script ID non deve essere interpretato come una rinomina implicita di un record esistente. Le operazioni per creare una copia distinta, gestire le revisioni e affrontare modifiche concorrenti saranno approfondite separatamente.
28. Tornare al codice con Focus source
Terminata la compilazione dei metadati, si possono nascondere i pannelli secondari dal menu View e recuperare l’ampia area dell’editor con Focus source.
L’editor conserva il proprio tema autentico High Contrast Dark. La cornice esterna della finestra può restare chiara senza compromettere la leggibilità del sorgente.

Il capitolo successivo sarà dedicato alle operazioni New Script, Save, Save As, Delete e Close, inclusi i casi di modifiche non salvate e la protezione delle revisioni.