GX-TXT Python Script Workspace: costruire un Project multifile ed esplorarlo con il debugger
Questo tutorial illustra come creare un vero Project Python con un file principale e un package di funzioni ausiliarie, salvarlo come unica revisione, seguire l’esecuzione nel debugger nativo e leggere Call Stack, Locals e Globals. Le elaborazioni impiegano dati sintetici: nessuno strumento o Dataset reale è necessario.
1. Obiettivo scientifico e didattico
Realizzeremo una semplice calibrazione moltiplicativa con letture sintetiche [1.0, 4.0, 9.0] e fattore 2.0. La funzione di supporto restituisce [2.0, 8.0, 18.0]; il risultato finale atteso è 28.0. L’esempio serve a comprendere la distinzione fra sorgente principale, file helper, Project Registry, Debug Job e output del programma. Non calcola incertezze e non pubblica Dataset.
2. Che cos’è un Project Python in GX-TXT
Uno Script singolo contiene un solo sorgente; un Project raccoglie più file Python con identità, entrypoint e revisione comuni. I file helper vengono importati dal principale seguendo la normale sintassi Python, ma sono conservati come parte di uno snapshot del Project. Non serve aprire Script Library: tutte le operazioni descritte sono disponibili direttamente in Python Script Workspace.
3. Creare il Project dalla finestra originale
Aprire una propria Session, avviare Python Script Workspace, quindi scegliere Project → New Project…. Nel form impostare un nome descrittivo, un Stable ID come w03_multifile_debug_project, Scope su session e Entrypoint su main.py. Premere Create project. Lo scope Session tiene insieme il lavoro nel contesto scientifico corrente.

4. La struttura dei tre file
La struttura da ottenere nel Project è:
main.py
helpers/
__init__.py
numeric.py
main.py costituisce l’entrypoint; helpers/numeric.py contiene il calcolo; helpers/__init__.py identifica il package. I percorsi sono relativi al Project. Non vanno sostituiti con percorsi assoluti del computer.
5. Scrivere main.py
Nel riquadro centrale modificare main.py. L’esempio importa calibrate dal file helper, definisce tre letture artificiali, chiama analyze e stampa il totale. La funzione controlled_spin aggiunge un ciclo limitato nel tempo per osservare il comando Pause: è una dimostrazione del debugger, non un modello efficiente di attesa nei programmi scientifici.

6. Aggiungere un file helper
Scegliere Project → New file…. Inserire il percorso relativo helpers/numeric.py, quindi confermare con Apply. L’editor apre il nuovo file in una scheda autonoma. Scrivere le due funzioni calibrate e scale_one; quest’ultima verrà raggiunta utilizzando Step Into.

7. Aggiungere helpers/__init__.py
Ripetere Project → New file… con helpers/__init__.py. In questo esempio basta un commento che descriva il package. Non creare una directory separata esternamente: il comando della GUI registra il file e lo include nel Project.
8. Il codice completo dei tre file
Il programma seguente corrisponde al Project usato nell’esercitazione. Tutti i commenti presenti nel codice sono in inglese.
main.py
# Synthetic Python Project for calibration and native multi-file debugging.
import time
from helpers.numeric import calibrate
READINGS = [1.0, 4.0, 9.0]
FACTOR = 2.0
def controlled_spin(seconds):
deadline = time.monotonic() + seconds
counter = 0
while time.monotonic() < deadline:
counter += 1
return counter
def analyze(readings, gain):
baseline = [float(value) for value in readings]
scaled = calibrate(baseline, gain)
summary = {"count": len(scaled), "sum": sum(scaled)}
return summary
def main():
summary = analyze(READINGS, FACTOR)
ticks = controlled_spin(12.0)
print(f"PROJECT_SUM {summary['sum']:.2f} SAMPLES {summary['count']}")
print("PROJECT_SPIN_DONE", ticks >= 0)
if __name__ == "__main__":
main()
helpers/numeric.py
# Synthetic numerical helper: nested Python functions for the debugger.
def scale_one(value, factor):
normalized = float(value)
result = normalized * float(factor)
return result
def calibrate(values, factor):
source = list(values)
count = len(source)
scaled_first = scale_one(source[0], factor)
scaled_rest = [scale_one(value, factor) for value in source[1:]]
corrected = [scaled_first] + scaled_rest
return corrected
helpers/__init__.py
# Python helper package for this synthetic scientific Project.
9. Salvare in modo coerente con Save All
Usare File → Save All quando i tre buffer sono pronti. GX-TXT registra una revisione coerente dell’intero Project, con identificazione dei file, entrypoint e impronte del contenuto. Le stelle di modifica delle schede devono sparire. Il salvataggio non implica l’esecuzione del codice; per la riproducibilità scientifica il Job deve sempre riferirsi allo snapshot effettivamente salvato.

10. Come funziona l’import dei helper
La riga from helpers.numeric import calibrate indica al Python gestito di importare calibrate dal package del Project. La funzione calibrate chiama scale_one, che trasforma ciascun valore in float e lo moltiplica per il fattore. analyze somma i risultati. Si tratta di normale Python; non occorre invocare API interne di GX-TXT per trovare i file Project. Il runtime verifica invece che lo snapshot multifile e i nomi dei sorgenti siano ammessi.
11. Preparare un breakpoint nel file helper
Aprire helpers/numeric.py dalla struttura Project. Portare il cursore alla riga 10, scaled_first = scale_one(source[0], factor), e premere F9. Un indicatore nel margine identifica il punto di arresto. Un breakpoint è associato al file e alla riga, non semplicemente al numero 10 dell’entrypoint.

12. Che cosa cambia quando si usa il debugger
Un normale Run Job esegue il programma fino alla conclusione oppure a un errore; il Debugger controlla un Job gestito durante la sua esecuzione e può sospenderlo a punti definiti. I pulsanti del debugger sono operazioni sul Job effettivo, non semplici animazioni nell’editor. Quando è attivo un Debug Job, il codice in esecuzione rimane uno snapshot immutabile.
13. Aprire Debug Session script…
Nel menu Run, scegliere Debug Session script…. Il pannello inferiore mostra Start Debug, Continue, Pause, Stop, Step Into, Step Over e Step Out. Aprire soltanto le sezioni Stack and variables necessarie alla spiegazione; per il lavoro ordinario è preferibile tenere chiusi i pannelli superflui.

14. Avviare il Job di debug e riconoscere la prima pausa
Premere Start Debug. Il runtime crea un Job Python gestito e, prima di proseguire nel codice, espone la pausa iniziale. Lo stato PAUSED e la freccia di esecuzione indicano la prossima istruzione. In questo stato si possono già osservare i controlli, ma i valori locali più interessanti compariranno quando si entrerà nella funzione di calibrazione.

15. Continue fino alla chiamata calibrate
Premere Continue. L’esecuzione raggiunge il breakpoint nella funzione calibrate, riga 10 di helpers/numeric.py, prima di invocare scale_one. L’indicatore del breakpoint e la freccia di esecuzione sono distinti. Qui si può leggere la lista di ingresso della funzione e il fattore, mentre le assegnazioni successive non sono ancora avvenute.

16. Selezionare il frame chiamante
Nel Call Stack, scegliere il frame analyze. La sorgente visibile passa a main.py, mentre l’interprete resta realmente fermo nel frame di calibrate. Selezionare il frame non equivale a Continue né sposta il punto di esecuzione; permette di esaminare lo stato di un chiamante.

17. Leggere l’ordine delle chiamate
La sequenza visibile comprende calibrate, analyze, main e il frame di modulo. La cima della pila corrisponde alla funzione in cui è avvenuta la sospensione; sotto si trovano i chiamanti. Il numero di riga indicato accanto a un frame identifica la sua posizione sorgente, mentre la freccia gialla è riservata all’effettivo punto di esecuzione.

18. Interpretare Locals e Globals
Il pannello Locals / Globals espone nomi, tipi, forme e valori entro limiti di visualizzazione. Nel frame calibrate, factor vale 2.0, source ha tre valori, count vale 3; funzioni e moduli vengono mostrati come oggetti opachi. Quando si passa al frame analyze, cambiano i valori locali osservabili. Una variabile non ancora assegnata non deve essere interpretata come già calcolata.

19. Step Into: entrare nella funzione annidata
Tornare al frame superiore calibrate e premere Step Into. In questo programma si entra realmente nella funzione scale_one, fermandosi alla riga 3 prima dell’istruzione normalized = float(value). È il comando adatto quando si vuole ispezionare il funzionamento di un helper anziché trattarlo come un’unica operazione.

20. Step Over: eseguire la riga corrente
Premere Step Over per eseguire l’assegnazione corrente senza entrare in una nuova chiamata. La successiva istruzione osservata è la riga 4 di scale_one, result = normalized * float(factor). Il debug resta all’interno della stessa funzione e consente di osservare come cambiano i valori locali.

21. Step Out: tornare alla funzione chiamante
Premere Step Out. L’esecuzione completa scale_one e torna in calibrate, alla riga 11, dove viene preparata la trasformazione degli altri elementi. Il debugger non elimina alcun frame: visualizza il naturale ritorno della chiamata Python e l’aggiornamento della pila.

22. Completare il primo Debug Job
Premendo Continue, il programma completa la calibrazione, esegue il ciclo limitato e scrive:
PROJECT_SUM 28.00 SAMPLES 3
PROJECT_SPIN_DONE True
Il Job termina con stato COMPLETED, codice d’uscita 0 e flusso stderr vuoto. Il risultato conferma matematicamente la somma 2 + 8 + 18 = 28. Il codice non ha pubblicato un Dataset canonico: si tratta di output testuale. Un eventuale comando Pause accettato durante un Job in esecuzione non garantisce, da solo, che il successivo stato osservato sia PAUSED.

23. Preparare la dimostrazione del Pause asincrono
Per osservare un Pause effettivo, terminare e chiudere il Debugger, aprire di nuovo il Project se necessario, togliere il precedente breakpoint dalla funzione helper e collocare F9 alla riga 24 di main.py, dopo il ciclo controlled_spin. Il nuovo breakpoint rimarrà da raggiungere; il ciclo utilizza un limite di dodici secondi soltanto per rendere visibile lo stato RUNNING. Avviare un nuovo Start Debug, superare la pausa iniziale e premere Continue.

24. Pause durante RUNNING: osservare il risultato effettivo
Quando il Debugger riporta RUNNING, premere Pause. In questa prova la richiesta ha realmente portato a PAUSED nella funzione controlled_spin, alla riga 12. La freccia indica l’istruzione counter += 1. L’esempio mostra che il comportamento asincrono dipende dall’adapter e dalla situazione di esecuzione: verificare sempre il vero stato finale anziché limitarsi al click del pulsante.

25. Locals durante Pause e differenza tra Stop e Completed
Durante questa pausa, Locals mostra seconds = 12.0, deadline e counter con i valori osservati dal Python in esecuzione. Per interrompere la dimostrazione utilizzare Stop: lo stato terminale di questo secondo Debug Job è CANCELLED, non COMPLETED. È corretto distinguere il primo Job concluso con il totale 28 dalla seconda esecuzione interrotta volontariamente.

26. Chiudere il debugger, riaprire il Project e conservare il lavoro
Chiudere il pannello del debugger quando il Job è terminale. Se l’editor non permette di inserire o togliere un breakpoint pur non avendo più un Job attivo, salvare il lavoro ed eseguire la normale sequenza File → Close, riaprire Python Script Workspace e scegliere Project → Open Project…: il Project salvato riappare con entrypoint e contenuti invariati. Questa procedura è stata verificata con il normale percorso GUI. Tenere poi i pannelli opzionali chiusi per restituire spazio al codice. Il Project rimane nella Session; non serve Script Library, non sono stati modificati strumenti e non è stato creato un Dataset.