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.

Editor Python GX-TXT High Contrast Dark con progetto salvato e file main.py marcato come entrypoint
Figura 1. Il progetto inizia con un solo file di ingresso, main.py, identificato come principale nell’albero dei sorgenti.

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.

Finestra originale New file di GX-TXT con campo Normalized relative source path e pulsanti Apply e Cancel
Figura 2. Project → New file apre una finestra che accetta percorsi sorgente relativi e sottocartelle.

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]
Workspace Python con albero helpers, file calculation.py e sorgente colorato con funzione scale_readings
Figura 3. Il nuovo helpers/calculation.py contiene una funzione illustrativa e resta modificato finché non viene salvato.

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

FileFunzione nel progetto
main.pyEntrypoint, usa la funzione ausiliaria e prepara i risultati
helpers/calculation.pyModulo con la funzione scale_readings
helpers/__init__.pyInizializzazione 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.

Python Script Project con tre schede modificate: main.py, calculation.py e file di inizializzazione del package helpers
Figura 4. Le schede dei tre file riportano l’asterisco quando vi sono modifiche non ancora registrate.

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.

Editor Python dopo Save All, tre schede senza asterisco e progetto multisorgente salvato nella Session
Figura 5. File → Save All salva tutti i sorgenti modificati nella stessa revisione del Project e rimuove gli indicatori di modifica.

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.

Finestra originale Rename move file con percorso helpers/calculation.py e controllo Apply
Figura 6. Rename/move file propone il percorso corrente e consente di cambiarlo mantenendo un nome relativo al progetto.

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.

Editor Python con helper rinominato calibration.py nel package helpers e Main distinto
Figura 7. Dopo Rename/move file, l’albero e la scheda mostrano helpers/calibration.py.

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
main.py in GX-TXT con import da helpers.calculation ancora presente dopo rinomina del modulo
Figura 8. Rinominare un file non riscrive automaticamente le istruzioni import che puntavano al nome precedente.

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
Editor Python con from helpers.calibration import scale_readings e albero che contiene calibration.py
Figura 9. Correggere l’import in main.py e salvare il Project rende coerenti l’istruzione e il file rinominato.

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.

Albero Python Project con helpers/calibration.py marcato come main e main.py privo del marcatore
Figura 10. Set entrypoint può designare temporaneamente il file ausiliario come principale: l’albero mostra il marcatore main.

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.

Messaggio originale GX-TXT Select another entrypoint before removing this file con pulsante OK
Figura 11. Il file designato come entrypoint non può essere rimosso finché non si seleziona un altro file principale.

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.

Dialogo originale GX-TXT che chiede conferma per Remove helpers/obsolete.py con pulsanti OK e Cancel
Figura 12. La rimozione di un file non principale richiede una conferma esplicita e permette 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
Python Project con tre file coerenti e stato Saved nella barra inferiore revisione r11
Figura 13. La revisione conclusiva contiene main.py, helpers/calibration.py e helpers/__init__.py, tutti salvati.

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.

Python Script Workspace riaperto con albero del package helpers e codice originale scale_readings in calibration.py
Figura 14. Dopo aver riaperto il Viewer, l’albero consente ancora di selezionare il modulo ausiliario salvato.

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.

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.