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.

Originale GUI Project Canvas GX-TXT con formulario New Project in scope Session.
Figura 1. Project Canvas permette di registrare un Project Python della Session con entrypoint main.py.

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.

Dialogo Tk Project New file con percorso relativo helpers/numeric.py.
Figura 2. Project → New file aggiunge un file helper con percorso relativo alla radice 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.

Editor Python GX-TXT con codice sintetico della funzione calibrate nel file helper.
Figura 3. Il file helpers/numeric.py contiene la funzione calibrate e variabili con tipi e forme verificabili.

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.

Editor Python GX-TXT main.py con import helpers.numeric e funzioni analyze e main.
Figura 4. L’entrypoint main.py importa calibrate dal package helpers del Project registrato.

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.

Editor Project Python GX-TXT con albero dei tre file e package helpers.
Figura 5. File → Save All registra i tre file del Project e conserva la revisione comune.

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.

Editor Python file helper con breakpoint rosso sulla riga 7 metadata.
Figura 6. F9 nel file helper crea un breakpoint alla riga fisica 7 della funzione calibrate.

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.

Pannelli originali Debugger Call Stack e Locals/Globals in stato IDLE.
Figura 7. Nel capitolo Call Stack si aprono intenzionalmente i pannelli Stack e Locals/Globals del debugger.

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.

Editor Python con Project Debug inizialmente PAUSED nell’entrypoint main.py.
Figura 8. Start Debug si ferma sulla prima istruzione del Project registrato prima di raggiungere il helper.

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.

Editor Python con file helpers/numeric.py e freccia gialla sul breakpoint alla riga 7.
Figura 9. Il Debugger si ferma sulla riga 7 di helpers/numeric.py, all’interno di calibrate.

12. I quattro frame effettivamente osservati

Il Call Stack presenta questa sequenza di funzioni attive, dall’interno verso l’esterno:

FrameFunzioneFileRiga
0calibratehelpers/numeric.py7
1analyzemain.py10
2mainmain.py16
3<module>main.py20

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.

Colonna Function originale del Call Stack con calibrate, analyze, main e module, senza percorsi locali.
Figura 10. Il Call Stack originale elenca calibrate, analyze, main e module in ordine di chiamata.

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.

Pannello originale Locals/Globals: valori factor, source, count, scaled e bounded nel frame calibrate.
Figura 11. Locals / Globals riporta tipi, shape e valori del frame selezionato calibrate.

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.

Editor Python main.py alla riga 10 mentre il frame selezionato è analyze.
Figura 12. Selezionando analyze nel Call Stack si apre main.py alla riga 10, senza muovere l’interprete.

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.

Pannello originale Locals/Globals del frame analyze con baseline shape 3 e gain 2.0.
Figura 13. Nel chiamante analyze la lista baseline è già assegnata, ma scaled non esiste ancora.

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.

Pannello originale Globals del Project con CALIBRATION_LABEL sintetico e READINGS shape 3.
Figura 14. Il frame main mostra le variabili globali CALIBRATION_LABEL e READINGS dell’entrypoint.

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.

Editor Python di nuovo nel file helper sulla riga 7, frame0 selezionato.
Figura 15. Tornando a frame0 si visualizza nuovamente calibrate, la funzione realmente sospesa.

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.

Editor Python dopo Stop: freccia di esecuzione rimossa e Job terminato CANCELLED.
Figura 16. Stop cancella il Job Debug e rimuove l’indicatore di esecuzione del sorgente.

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.

Python Script Workspace riportato al Project originale con tema High Contrast Dark.
Figura 17. Al termine il Workspace torna alla visualizzazione originale High Contrast Dark.