GX-TXT Python Script Workspace: organizzare un progetto Python con più file e Save All
Un programma scientifico può diventare più facile da mantenere quando il codice viene separato in un file di ingresso, moduli ausiliari e package Python. In GX-TXT, Python Script Workspace permette di aggiungere e modificare questi sorgenti direttamente nel Project, navigare fra le schede e registrarli insieme tramite File → Save All.
La guida mostra i comandi dell’interfaccia e il rapporto fra codice modificato e revisione salvata. Utilizzeremo soltanto un esempio numerico sintetico: la creazione, la modifica e il salvataggio dei file non eseguono lo Script, né producono Dataset.
1. Partire da un Python Script Project
Aprire Viewers → Python Scripts e selezionare un Project registrato tramite Project → Open Project… e Open entrypoint. Per creare prima il Project, seguire il capitolo dedicato a New Project.
La nuova struttura nasce da un Project con un solo main.py, già registrato. I comandi descritti qui operano sull’identità del Project aperto, e non su una cartella esterna scelta arbitrariamente.
2. Riconoscere l’entrypoint
Nell’albero dei file il file principale è indicato dal marcatore (main). In un Project appena creato, normalmente compare main.py con il commento iniziale # Project entrypoint.

L’entrypoint identifica il file da cui partirà una futura esecuzione gestita. Il solo fatto di aprirlo o selezionarlo non avvia Python.
3. L’albero dei sorgenti e le schede
Il Project mostra un albero dei file accanto al Source. I percorsi delle sottocartelle possono essere espansi per visualizzare i relativi moduli; scegliendo un file viene aperta o riutilizzata la sua scheda.
Ogni scheda conserva il proprio testo, cursore e stato di modifica. L’albero appartiene al Project aperto: non va confuso con Script Explorer / Registered scripts, che elenca identità di Script differenti.
4. I comandi Project per i file
Nel menu Project sono presenti Open project file…, New file…, Rename/move file…, Remove file e Set entrypoint.
Questi comandi lavorano sui sorgenti ammessi del Project. Per operazioni di scrittura serve un Project registrato e modificabile nel contesto corretto; uno snapshot storico in sola lettura non è una destinazione valida per nuove revisioni.
5. Creare un file con un percorso relativo
Scegliere Project → New file…. Compare una finestra con il campo Normalized relative source path (subfolders allowed) e i pulsanti Apply e Cancel.

Scrivere, per esempio, helpers/calculation.py. È un percorso relativo alla radice del Project: helpers è la sottocartella, calculation.py il nuovo file Python. Cancel chiude la finestra senza registrare nulla.
6. Scrivere un modulo ausiliario
Dopo Apply, il Project registra il nuovo file vuoto e lo apre in una scheda indipendente. È possibile scrivere una funzione per elaborare dati sintetici:
# Synthetic calibration helper; not executed.
def scale_readings(values, factor=1.5):
"""Return scaled synthetic readings."""
return [round(value * factor, 3) for value in values]

L’esempio moltiplica i valori per un fattore numerico. Non utilizza funzioni private di GX-TXT e non impone alcuna API scientifica per la sola modifica del sorgente.
7. Aggiungere il package helpers
Per organizzare esplicitamente i file come package, creare anche helpers/__init__.py tramite Project → New file….
Il file può contenere soltanto un commento:
# Synthetic Python package for calibration helpers.
Il package helpers e i moduli al suo interno appariranno nell’albero del Project. Il file __init__.py non svolge da solo un calcolo.
8. Collegare il file principale al modulo
Aprire main.py dall’albero e preparare un’istruzione di import esplicita. Con il modulo iniziale, un esempio è:
# Main Python project entrypoint; no execution in this tutorial.
from helpers.calculation import scale_readings
measurements = [1.0, 4.0, 9.0]
calibrated = scale_readings(measurements)
print(calibrated)
Il nome del modulo nell’import deve corrispondere al percorso del file. helpers/calculation.py è un percorso nel Project, mentre helpers.calculation è la forma del modulo usata dall’istruzione Python.
9. Come sono separati i file
| File | Funzione nel progetto |
|---|---|
main.py | Entrypoint, usa la funzione ausiliaria e prepara i risultati |
helpers/calculation.py | Modulo con la funzione scale_readings |
helpers/__init__.py | Inizializzazione del package helpers |
Il codice di questa guida rimane volutamente semplice. L’interpretazione fisica delle grandezze, l’accesso ai Dataset e l’eventuale pubblicazione dei risultati richiedono contratti e procedure scientifiche specifici.
10. Identificare le schede modificate
Quando vengono modificati file differenti, sulle rispettive schede compare un asterisco. La presenza di più asterischi indica che vi sono più buffer da salvare.

Il cambio di scheda non salva automaticamente il codice. Tornando su un altro file, le modifiche ancora non registrate restano disponibili nell’editor.
11. Salvare con File → Save All
Scegliere File → Save All per registrare le modifiche del Project. Il Workspace raccoglie i sorgenti interessati e li salva come una nuova revisione coerente del progetto, anziché registrare una revisione separata per ciascuna scheda del medesimo Project.

Dopo il salvataggio, verificare che gli asterischi siano scomparsi e che la barra di stato mostri Saved.
12. La revisione riguarda l’intero Project
Il Registry mantiene un’identità del Project e una revisione associata all’insieme dei sorgenti. Il salvataggio registra il contenuto completo, l’entrypoint e le informazioni necessarie a riconoscere esattamente quella versione.
In un esempio multisorgente, i tre file modificati insieme vengono quindi associati alla stessa revisione. Non si devono interpretare le tre schede come tre Project autonomi.
13. Aprire un altro file dall’albero
Fare clic sul nome di un file sotto helpers per passare al suo sorgente. Per ritornare al programma principale, scegliere main.py.
In alternativa Project → Open project file… offre le voci presenti nel Project. Aprire una scheda non modifica il codice e non cambia il file designato come entrypoint.
14. Rinominare o spostare un file
Per modificare il percorso di un file, attivare la sua scheda e selezionare Project → Rename/move file…. La finestra propone il percorso corrente.

Si può sostituire helpers/calculation.py con helpers/calibration.py. Anche questo è un percorso relativo al Project. Cancel lascia tutto invariato; Apply richiede il salvataggio della nuova struttura del Project.
15. Controllare la rinomina
Dopo Apply, il nuovo nome compare sia nella scheda sia nell’albero dei file.

Il Project mantiene l’identità complessiva, ma registra una nuova versione della struttura. La rinomina non deve essere considerata soltanto un cambiamento di etichetta: il percorso fa parte dell’identità del file Python.
16. Gli import non vengono aggiornati automaticamente
Dopo aver rinominato il modulo, tornare su main.py. L’istruzione precedente può essere ancora:
from helpers.calculation import scale_readings

Rename/move file non corregge automaticamente gli import presenti negli altri sorgenti. Se il vecchio modulo non è più nel Project, l’import va aggiornato manualmente prima di utilizzare il programma.
17. Correggere l’istruzione di import
Nel nostro esempio, la nuova dichiarazione è:
from helpers.calibration import scale_readings

Dopo aver corretto il codice, utilizzare Save All per registrare la modifica. Il salvataggio verifica la struttura del sorgente ma non sostituisce la futura verifica dell’import nel runtime Python.
18. Cambiare il file di ingresso
Per designare un altro file come principale, selezionarlo nell’albero e usare Project → Set entrypoint. Il marcatore (main) si sposta sul file scelto.

Questa funzione è utile quando un progetto possiede più possibili programmi di ingresso. Un file contenente soltanto funzioni ausiliarie non dovrebbe diventare l’entrypoint definitivo se non è stato progettato per essere eseguito direttamente.
19. Ripristinare main.py come entrypoint
Tornare su main.py e scegliere nuovamente Project → Set entrypoint. L’albero riporta (main) accanto al file principale.
Ogni modifica dell’entrypoint viene registrata come nuova revisione del Project. I file non vengono copiati, cancellati o eseguiti dal solo cambio di designazione.
20. Protezione dalla rimozione dell’entrypoint
Con main.py designato come principale, provare Project → Remove file su quel file. GX-TXT rifiuta l’operazione e richiede di selezionare prima un altro entrypoint.

Questo controllo evita di creare accidentalmente un progetto senza file di ingresso. Premendo OK si torna all’editor senza modificare la struttura salvata.
21. Rimuovere un file ausiliario
Per un sorgente che non è l’entrypoint, Remove file richiede una conferma esplicita. Il dialogo mostra il percorso preciso del file e i pulsanti OK e Cancel.

Leggere il percorso prima di accettare: la conferma rimuove il file dal Project e registra la modifica dell’insieme dei sorgenti.
22. Cancel e conferma non sono equivalenti
Con Cancel, il file ausiliario rimane nell’elenco e la revisione salvata non cambia. Con OK, un file temporaneo non principale viene rimosso e il Project conserva gli altri file.
Quando si lavora con un package Python, verificare prima che nessun altro sorgente importi il modulo che si intende rimuovere. GX-TXT non può dedurre automaticamente tutta la logica delle dipendenze del programma.
23. La scorciatoia Ctrl+Shift+S
Ctrl+Shift+S richiama la stessa operazione Save All dal Workspace. È utile quando si sta modificando un programma che comprende varie schede.
Il suo effetto deve essere controllato nella barra di stato e nei marcatori delle schede. La scorciatoia salva il sorgente, non avvia il Runner e non genera un Job.
24. Quando il Project è cambiato nel Registry
Se la revisione o l’impronta del Project salvato non coincide più con quella attesa dall’editor, GX-TXT rifiuta il salvataggio e richiede un nuovo controllo.
Questa protezione evita di sovrascrivere silenziosamente una versione aggiornata da un altro contesto. In tal caso è opportuno rivedere il Project registrato, conservare il lavoro locale e aprire la versione corretta prima di riprovare.
25. Quali percorsi e sorgenti sono ammessi
I percorsi devono essere relativi, normalizzati e riferiti a file .py. Non sono ammessi percorsi assoluti, riferimenti a directory superiori tramite .. o nomi che escono dal Project.
Il validatore controlla inoltre integrità del manifesto, collisioni fra nomi, limiti di dimensione e determinati tentativi di caricare sorgenti esterni o sostituire moduli GX-TXT riservati. Questi controlli aiutano a mantenere coerente e portabile la struttura.
26. Il progetto conclusivo
Dopo le operazioni dimostrative, la struttura utile è tornata a tre file:
main.py (main)
helpers/
__init__.py
calibration.py

L’entrypoint importa scale_readings da helpers.calibration. Questa rappresentazione descrive il codice salvato, non un esperimento già eseguito.
27. Riaprire un Project multisorgente
Dopo aver chiuso e riaperto Python Script Workspace, usare Project → Open Project…, selezionare il progetto e premere Open entrypoint. Il file principale e l’albero dei sorgenti sono nuovamente disponibili.

Dall’albero si possono aprire nuovamente calibration.py e __init__.py senza modificare la revisione. I file letti devono corrispondere al contenuto salvato nel Registry.
28. Riepilogo
Con New file… si creano sorgenti relativi al Project; l’albero e le schede permettono di passare fra file indipendenti. Save All registra le modifiche del gruppo in una nuova revisione; Rename/move file…, Set entrypoint e Remove file modificano la struttura con controlli d’identità e conferma.
Ricordare che rinominare un modulo non aggiorna gli import e che salvare non significa eseguire. Prima di un futuro Job, verificare il file principale, la coerenza degli import, le dipendenze pubbliche e i dati di ingresso.
Il prossimo capitolo esaminerà le Note Markdown associate ai singoli sorgenti, la loro visualizzazione e le differenze fra modifica della nota e modifica del programma.