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.

Schermata originale GX-TXT del form New Project con dati sintetici.
Figura 1. Il modulo New project definisce nome, Stable ID, scope Session e main.py come entrypoint.

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.

Editor Python Dark con codice main.py prima di Save All.
Figura 2. Il file main.py viene scritto nell’editor Python High Contrast Dark.

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.

Sorgente Python originale della funzione helper calibrate e scale_one.
Figura 3. Il file helpers/numeric.py contiene due funzioni annidate per la calibrazione.

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.

Python Script Workspace dopo il salvataggio di un Project multifile.
Figura 4. Il Project contiene main.py e due file nel package helpers, tutti salvati.

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.

Editor GX-TXT con breakpoint F9 nella funzione calibrate.
Figura 5. F9 sulla riga 10 di helpers/numeric.py crea un breakpoint eseguibile.

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.

Python Script Workspace con Debugger nativo aperto in stato IDLE.
Figura 6. Il Debugger nativo Python mostra Start Debug, Continue, Pause e i controlli di avanzamento.

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.

Debugger Python nella pausa iniziale prima dell'esecuzione.
Figura 7. Start Debug apre un Job gestito e ferma il codice alla prima istruzione.

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.

Debugger Python con freccia di esecuzione e breakpoint su calibrate riga 10.
Figura 8. Continue raggiunge il breakpoint helper10 prima della chiamata scale_one.

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.

Editor Python dopo la selezione del frame chiamante nel Call Stack.
Figura 9. Selezionare il frame chiamante mostra main.py senza spostare il punto di esecuzione.

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.

Elenco delle funzioni nel Call Stack nativo, senza percorsi locali.
Figura 10. Call Stack elenca le funzioni calibrate, analyze, main e il modulo principale.

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.

Pannello originale Locals Globals del debugger Python.
Figura 11. Locals e Globals mostrano nomi, tipi e valori di variabili del frame selezionato.

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.

Python debugger dopo Step Into nella funzione helper annidata scale_one.
Figura 12. Step Into entra in scale_one e si ferma alla riga 3.

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.

Python debugger che mostra l'avanzamento Step Over nella funzione scale_one.
Figura 13. Step Over passa dall’assegnazione normalized alla riga 4 della funzione scale_one.

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.

Debugger Python dopo Step Out dalla funzione scale_one.
Figura 14. Step Out torna nella funzione calibrate alla riga 11.

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.

Debugger Python con Job scientifico completato.
Figura 15. Dopo Continue il Project completa realmente il calcolo sintetico.

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.

Debugger Python con breakpoint successivo nel file main.py.
Figura 16. Un breakpoint successivo nel main.py permette di dimostrare Pause durante RUNNING.

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.

Debugger Python fermo con Pause asincrono nella funzione controlled_spin.
Figura 17. Pause durante RUNNING sospende veramente controlled_spin alla riga 12.

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.

Pannello Locals Globals durante la sospensione controllata della funzione Python.
Figura 18. Durante Pause i Locals mostrano seconds, deadline e counter nella funzione.

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.