GX-TXT Python Script Workspace: Call Stack, Locals, Globals e frame dei file helper
Il debugger Python nativo di GX-TXT consente di esaminare la catena delle chiamate e i valori delle variabili mentre un Job è realmente PAUSED. Nella scheda Stack and variables si possono selezionare diversi frame per conoscere il contesto delle funzioni chiamanti, distinguendo la posizione effettiva dell’interprete dalla posizione del frame che si sta osservando. Questa guida usa un Project Python della Session con un entrypoint e un file helper, senza strumenti fisici né Dataset scientifici.
1. Perché utilizzare Call Stack
Quando un programma richiama più funzioni, un singolo file o una sola riga evidenziata non bastano per capire come sia stato raggiunto un calcolo. Il Call Stack indica quali funzioni sono attive e quali si sono chiamate a vicenda. Locals / Globals mostra i valori del frame selezionato, non necessariamente quelli del frame più interno. La GUI conserva un riferimento verificato al sorgente registrato e al Job corrente, per evitare di mescolare dati di revisioni diverse.
2. Preparare un Project Python di Session
In Python Script Workspace, scegliere Project → New Project… e compilare nome, identificativo, Scope: Session ed Entrypoint: main.py. Un Project contiene più file sorgente ma viene gestito da una singola identità registrata. Il nuovo Project didattico serve soltanto a mostrare il passaggio fra un entrypoint e un helper. Non occorre aprire la Script Library.

3. Aggiungere il file helper
Dal Project aperto, usare Project → New file… e indicare un percorso relativo, per esempio helpers/numeric.py. Il dialogo originale accetta un nome interno al Project e registra il nuovo file nello stesso insieme di sorgenti. Non sostituire questo percorso relativo con un file arbitrario esterno alla Session: il debugger deve poter verificare che ogni frame appartenga ai file ammessi dalla revisione del Project.

4. Una funzione con variabili scientifiche sintetiche
Nel file helper, definiamo calibrate, che riceve tre valori e un fattore numerico. Durante il calcolo crea una lista temporanea, la sua lunghezza, una seconda lista con valori riscalati e una piccola struttura dict. Questi oggetti permettono di osservare i tipi e le dimensioni nel debugger.
def calibrate(values, factor):
source = list(values)
count = len(source)
scaled = [float(value) * float(factor) for value in source]
bounded = scaled[:12]
metadata = {"count": count, "unit": "arb"}
return bounded
I dati sono inventati e non costituiscono una calibrazione sperimentale.

5. L’entrypoint importa il file helper
Nel file main.py, importare la funzione tramite from helpers.numeric import calibrate. La funzione analyze crea baseline, richiama l’helper e costruisce un riepilogo. La funzione main richiama analyze con tre campioni e un fattore. I valori globali CALIBRATION_LABEL, READINGS e GAIN rimangono disponibili nel modulo dell’entrypoint.

6. Salvare insieme i file del Project
Aggiungere anche helpers/__init__.py, quindi utilizzare File → Save All per registrare i buffer del Project. I tre file diventano parte della stessa revisione e del relativo SHA-256 complessivo. Il singolo Job Debug eseguirà quella revisione, non una combinazione di vecchie e nuove versioni del helper.

7. La differenza fra un Script singolo e un Project
Uno Script registrato come file singolo presenta normalmente i frame appartenenti a quel sorgente. Un Project Python, invece, può ammettere anche i frame di file helper registrati nella medesima revisione. Il Debugger non tratta indistintamente come file dell’esperimento tutto il codice della libreria standard Python: filtra la catena dei frame secondo i file consentiti dal manifesto del Project.
8. Impostare un breakpoint nel helper
Nell’albero del Project selezionare helpers/numeric.py. Portare il cursore sulla riga eseguibile 7, dove viene preparato metadata, e premere F9. Il punto rosso deve apparire nel margine del file helper e rimanere associato a quel file, non alla riga 7 di main.py. Un breakpoint di Project è quindi identificato da file e riga, oltre che dalla revisione del sorgente.

9. Aprire intenzionalmente Stack and variables
Scegliere Run → Debug Session script…, poi aprire la scheda Stack and variables. Per questo capitolo sono utili entrambe le viste: Call Stack a sinistra e Locals / Globals a destra. Nelle operazioni di editing quotidiane è invece preferibile lasciare questi pannelli chiusi, così da mantenere più spazio per il codice.

10. Start Debug e la pausa iniziale
Premere Start Debug sul Project salvato e pulito. Come nella guida precedente, il debugger Python può effettuare una prima sospensione sulla prima istruzione dell’entrypoint, prima della chiamata all’helper. La scheda Stack viene popolata man mano che il Job raggiunge i punti di arresto. Il pulsante Start Debug crea un Job reale e gestito dal supervisore; aprire il pannello IDLE, da solo, non lo crea.

11. Continue fino al breakpoint del helper
Premere Continue. Il programma esegue main, passa a analyze e chiama calibrate dal file helpers/numeric.py. L’esecuzione si interrompe sulla riga 7 del helper con stato PAUSED. GX-TXT porta in primo piano il file registrato corrispondente e disegna la freccia gialla accanto al breakpoint rosso.

12. I quattro frame effettivamente osservati
Il Call Stack presenta questa sequenza di funzioni attive, dall’interno verso l’esterno:
| Frame | Funzione | File | Riga |
|---|---|---|---|
| 0 | calibrate | helpers/numeric.py | 7 |
| 1 | analyze | main.py | 10 |
| 2 | main | main.py | 16 |
| 3 | <module> | main.py | 20 |
Il frame 0 è quello in cui l’interprete si trova realmente fermo. I successivi descrivono le chiamate che hanno condotto a quel punto. I numeri di riga rappresentano le posizioni nei rispettivi file della revisione eseguita.

13. Locals nel frame calibrate
Selezionando il frame 0, i Locals comprendono values, factor, source, count, scaled e bounded. Nella pausa osservata, factor è un float di valore 2.0, count è un int di valore 3, mentre scaled è una list di lunghezza 3 contenente 2.0, 8.0, 18.0. La variabile metadata non è ancora assegnata, perché l’interprete è fermo prima dell’esecuzione della sua riga.

14. Selezionare il frame chiamante analyze
Fare clic sulla riga analyze nel Call Stack. GX-TXT seleziona il frame 1 e apre main.py alla riga 10, dove si trova la chiamata calibrate(baseline, gain). Questo è un passaggio di ispezione, non di esecuzione: non equivale a Step Out, non modifica le variabili e non fa proseguire Python.

15. I Locals cambiano con il frame selezionato
Nel frame analyze, il valore gain è 2.0, e baseline contiene i tre ingressi sintetici in una lista di shape 3. La variabile locale scaled non è ancora presente, perché la chiamata all’helper non ha ancora restituito il risultato. Confrontare questo pannello con i Locals del frame calibrate permette di comprendere quali assegnazioni sono state già eseguite in ogni funzione.

16. Il frame main e le variabili globali
Selezionando il frame 2, il contesto attivo per l’ispezione diventa main alla riga 16. Le variabili globali del file main.py comprendono CALIBRATION_LABEL, con tipo str e valore synthetic, e READINGS, una lista di tre numeri. Un Global appartiene al modulo del frame selezionato: cambiando da main.py al helper, anche il dizionario dei Globals può essere differente.

17. Che cosa indicano Type, Shape e Value
Il pannello Locals / Globals distingue il nome della variabile dal Type, dalla Shape e dal Value. float e int sono valori numerici scalari; una list può riportare una shape con il numero di elementi, e un dict il numero di coppie presenti. Il testo visualizzato non è necessariamente una serializzazione completa dell’oggetto Python: serve a descrivere in modo limitato e sicuro lo snapshot disponibile.
18. Ritornare al frame 0
Fare clic di nuovo su calibrate nella tabella Call Stack. Il file attivo torna a helpers/numeric.py, la posizione selezionata torna alla riga 7 e ricompaiono i Locals propri della funzione helper. L’interprete era rimasto fermo sullo stesso punto per tutta la navigazione: il cambio fra i frame non esegue nessuna nuova istruzione.

19. Frame selezionato e posizione reale dell’interprete
Nello snapshot nativo, GX-TXT conserva separatamente selected_frame, file e line del frame osservato, oltre a execution_file e execution_line della riga effettivamente sospesa. Quando si seleziona analyze, il pannello mostra main.py alla riga 10, ma l’esecuzione resta in calibrate alla riga 7. Questo dettaglio è fondamentale: la riga mostrata dopo una selezione non prova che il Job abbia eseguito un comando Step.
20. La relazione fra import e file del Project
Il helper è ammesso nel Debug perché appartiene al manifesto registrato del Project. Il codice from helpers.numeric import calibrate collega l’entrypoint al package. Quando il debugger si ferma nell’helper, la scheda del relativo file può essere aperta automaticamente. Non tutti i frame tecnici della libreria standard Python vengono inseriti fra i frame utente del Project: l’elenco è limitato ai sorgenti riconosciuti dal contratto.
21. Le osservazioni sono limitate, non una console Python
Il debugger non deve eseguire repr() o str() arbitrari sugli oggetti del ricercatore per costruire un inspector. I valori semplici possono essere mostrati direttamente; liste e dizionari sono rappresentati in forma limitata e gli oggetti complessi vengono indicati come opaque. Nell’esempio, una funzione è presentata come oggetto opaco anziché invocarne la rappresentazione. Questo comportamento riduce gli effetti collaterali e mantiene l’ispezione più prevedibile.
22. Limiti di lunghezza e profondità
La rappresentazione nativa limita il numero di variabili e gli elementi visualizzati: per esempio, la lettura dei Local e Global considera al massimo 128 voci per ambito, una lista mostra fino a 12 elementi e le stringhe sono troncate a una lunghezza massima definita. I livelli annidati più profondi possono essere omessi. Questi limiti si applicano allo snapshot dell’inspector, non alla dimensione reale delle strutture scientifiche utilizzate dal programma.
23. Perché Shape non coincide sempre con il numero totale di dati
Per una lista Python semplice la shape 3 indica tre elementi. Per un array NumPy, invece, la shape può avere più dimensioni e l’inspector può mostrare anche il dtype. I valori riportati nel pannello sono soltanto un’anteprima limitata e non sostituiscono una pubblicazione scientifica completa con Dataset canonico, unità, incertezze e metadati. Utilizzare lo snapshot per capire il flusso del codice, non per esportare misure.
24. Durante PAUSED le variabili rappresentano uno snapshot
Le righe dell’inspector sono valori osservati quando il Job è sospeso, riferiti alla revisione dello Script e al frame selezionato. Se si preme Continue o uno dei comandi Step, il programma può modificare tali valori: occorre attendere una nuova sospensione per leggerli nuovamente. Dopo un’eccezione, il debugger può distinguere l’ultima vista PAUSED dai dati già usciti dallo stack. Non assumere che una variabile mostrata dopo un evento terminale sia ancora un valore vivo del processo.
25. La selezione del frame non permette di alterare il Job
La tabella Call Stack permette di esaminare e navigare i frame; non costituisce un editor delle variabili del processo. Il controllo frame del Debugger richiede un indice valido e lo stesso Job/SHA-256 già verificato. Non è equivalente a cambiare l’entrypoint, modificare il file Python o spostare il puntatore di esecuzione. Per cambiare il calcolo occorre intervenire sul sorgente, salvarne una nuova revisione e iniziare un altro Job.
26. Fermare l’esercizio con Stop
Terminata l’ispezione, premere Stop. Il supervisore GX-TXT arresta il Job gestito; nell’esercizio il risultato terminale è CANCELLED, non COMPLETED. La GUI rimuove la freccia di esecuzione e chiude gli strumenti di osservazione alla chiusura del pannello Debugger. La gestione di Stop non modifica il Project registrato né pubblica Dataset di risultati.

27. Controllare la provenienza e le revisioni
Un’osservazione affidabile identifica il Project, il suo SHA-256, il Job e i file della revisione effettivamente eseguita. L’entrypoint e gli helper sono copiati nel contesto immutabile del Job. Se successivamente il Project cambia, il vecchio Call Stack rimane un dato storico di quella esecuzione; non va confrontato direttamente con righe e nomi di file di una revisione diversa senza verificarne il contenuto.
28. Tornare al normale Workspace
Chiudere il Debugger e riportare l’editor al codice originale in High Contrast Dark, con i pannelli di Call Stack e Locals / Globals chiusi per lasciare spazio al sorgente. La guida ha mostrato come passare da un helper al chiamante senza avanzare il Job e come leggere Type, Shape e Value con limiti di sicurezza. Nel prossimo capitolo verranno esaminate eccezioni Python, cancellazioni e protezioni contro le revisioni stale.
