GX-TXT Python Script Workspace: breakpoint, margine del sorgente e folding

Nel Python Script Workspace di GX-TXT, il margine sinistro del codice non serve soltanto a mostrare i numeri di riga: permette di inserire e gestire i breakpoint, segnala la riga raggiunta dal debugger e contiene i chevron per ripiegare i blocchi Python. Questa guida illustra i comandi reali dell’editor, la differenza tra punto abilitato e disabilitato, il folding e la relazione fra marcatori e revisioni registrate. Il codice dell’esempio è sintetico e non accede a strumenti fisici.

1. Preparare un sorgente Python leggibile

Aprire Python Script Workspace nella Session corretta e selezionare uno Script già registrato, oppure crearne uno con File → New Script e File → Save. Per esplorare il margine conviene chiudere i pannelli non necessari, lasciando visibile soprattutto il codice. La presentazione High Contrast Dark mantiene nero lo sfondo del testo, evidenzia le istruzioni Python e rende leggibili i marcatori della corsia laterale.

Editor Python High Contrast Dark con codice a funzioni, numerazione fisica delle righe e margine dei marcatori.
Figura 1. Uno Script Python registrato mostra numeri di riga, sintassi evidenziata e tre corsie nel margine.

2. Un piccolo programma adatto all’esercizio

Utilizziamo due funzioni Python: la prima normalizza una sequenza di valori e la seconda calcola un intervallo illustrativo. Sono presenti definizioni, condizioni, un ciclo e istruzioni eseguibili su righe diverse. Questo permette di vedere sia i breakpoint sia il folding, senza richiedere Dataset numerici o Job scientifici. Il seguente estratto mostra la struttura:

def normalize(values):
    # Return normalized synthetic values.
    scale = max(abs(value) for value in values)
    return [value / scale for value in values]

def summarize(samples):
    normalized = normalize(samples)
    results = []
    for value in normalized:
        results.append(round(value, 3))
    return min(results), max(results)

I commenti del sorgente sono in inglese; le istruzioni descrivono soltanto un esempio didattico.

3. Le tre corsie del margine

A sinistra della numerazione sono disposte tre aree differenti. La prima ospita i breakpoint, normalmente identificati da un cerchio rosso. La seconda è riservata all’indicatore della riga in esecuzione, rappresentato da una freccia gialla quando il debugger si ferma. La terza mostra i chevron di folding sui blocchi riconosciuti. Questi tre segnali possono trovarsi vicini, ma hanno significati indipendenti.

4. La numerazione identifica righe fisiche

Un breakpoint corrisponde a una riga fisica del sorgente, non alla posizione apparente dopo un ripiegamento. I numeri visualizzati nel margine permettono di trovare la stessa istruzione anche se altre sezioni vengono nascoste temporaneamente. I numeri di riga non cambiano quando si utilizza Fold current block o Fold all: il testo sorgente resta intatto.

5. Inserire un breakpoint con F9

Portare il cursore su una riga che contiene un’istruzione Python eseguibile, come l’assegnazione normalized = normalize(samples), quindi premere F9. Il margine mostra un cerchio rosso accanto alla riga. Nel nostro esempio la riga scelta è la 16. Il tasto F9 è un comando di editing dei marcatori: non esegue la funzione e non crea da solo un Job.

Editor Python con punto rosso di breakpoint sulla riga 16, funzione summarize.
Figura 2. F9 crea un punto rosso sulla riga eseguibile 16 senza modificare il sorgente.

6. Aggiungere un secondo punto con il mouse

Si può creare un punto anche facendo clic nella prima corsia del margine accanto a una riga eseguibile. Nell’esempio, un clic presso la riga 18 aggiunge un secondo breakpoint, indipendente da quello della riga 16. I due cerchi rossi significano che entrambi i punti sono abilitati. Tornare sulla riga 16 e premere ancora F9 ne cambia lo stato, rimuovendolo; un ulteriore F9 lo aggiunge nuovamente.

Editor Python con due breakpoint rossi abilitati alle righe 16 e 18.
Figura 3. Il margine può contenere più breakpoint su righe fisiche differenti.

7. Le righe non eseguibili vengono rifiutate

GX-TXT non permette di inserire un breakpoint su qualsiasi riga soltanto perché contiene del testo. Una riga vuota, un commento o una docstring priva di un’istruzione eseguibile vengono rifiutati. Il controllo utilizza il modello validato della struttura Python; se una riga non ha istruzioni eseguibili, l’editor mostra un messaggio nel proprio stato, senza creare il punto.

Editor Python con messaggio Line 5 has no executable Python instruction; no breakpoint set.
Figura 4. F9 non aggiunge breakpoint su una docstring priva di istruzioni Python eseguibili.

8. Attendere che il modello del sorgente sia pronto

Subito dopo un’apertura o una modifica, l’editor può aggiornare la propria analisi del sorgente. Se si tenta di inserire un punto mentre la struttura è in aggiornamento, il comando richiede di riprovare quando il modello sarà pronto. Non si tratta di un breakpoint accettato provvisoriamente: un punto diventa valido soltanto dopo il controllo della riga fisica. Evitare quindi clic ripetuti durante il ricalcolo della sintassi.

9. Il menu contestuale del margine

Fare clic con il pulsante destro nella corsia laterale di una riga. Il menu originale comprende Toggle breakpoint, Enable breakpoint, Disable breakpoint, Remove breakpoint, Clear all breakpoints e Fold / unfold current block. Le azioni agiscono sulla riga indicata oppure sull’insieme dei breakpoint, a seconda del comando. Il menu permette di gestirli senza modificare il testo Python.

Menu nativo del margine con Toggle breakpoint, Enable, Disable, Remove, Clear all e Fold/unfold.
Figura 5. Il menu contestuale del margine permette di abilitare, disabilitare, rimuovere e gestire folding.

10. Disabilitare non equivale a rimuovere

Disable breakpoint conserva il punto nella sua riga ma lo rende inattivo. Nell’editor il simbolo diventa un cerchio con il solo contorno, mentre i punti abilitati restano pieni. Enable breakpoint lo riattiva, e Remove breakpoint lo elimina. Questa distinzione è utile quando si vuole sospendere temporaneamente una condizione di arresto senza perdere il riferimento alla riga.

Editor Python con un breakpoint rosso abilitato e un punto disabilitato con solo contorno.
Figura 6. Un breakpoint disabilitato viene disegnato come cerchio vuoto e conserva la sua riga.

11. Aprire il pannello Breakpoints

Dal menu Run → Debug Session script… si può aprire il pannello del debugger senza premere Start Debug. Selezionare la scheda Breakpoints. In stato IDLE, l’elenco mostra la riga, lo stato Enabled, la funzione, il file sorgente, il riferimento registrato e la revisione SHA-256. Aprire soltanto questa scheda quando si vuole gestire i punti: Call Stack e Variables non servono ancora.

Pannello Debugger Breakpoints con righe 16 e 18, una Enabled yes e una Enabled no.
Figura 7. Il pannello Breakpoints IDLE elenca stato, riga, funzione e file senza avviare Python.

12. Navigare e riabilitare dal pannello

Selezionando una riga dell’elenco e premendo Go to source, il cursore torna all’istruzione corrispondente nel file. Si può inoltre utilizzare Enable per riattivare un punto disabilitato. Nell’esempio, la riga 18 passa da Enabled no a yes, mentre quella della riga 16 rimane indipendente. La gestione del pannello in stato IDLE non crea esecuzioni.

Pannello Debugger Breakpoints con due righe abilitate dopo il comando Enable.
Figura 8. Enable riattiva un punto disabilitato nel pannello Breakpoints.

13. Remove e Clear all nel pannello

Il pulsante Remove elimina soltanto il punto selezionato; gli altri rimangono nell’elenco e nel margine. Clear all, invece, elimina l’intera raccolta di punti abilitati e disabilitati del documento. Prima di eliminare tutto, controllare che si stia lavorando sul sorgente previsto. Chiudendo il pannello IDLE, l’editor ritorna alla normale visualizzazione del codice.

14. Cancellare tutti i punti da tastiera

Con il fuoco sul codice, Ctrl+Shift+F9 cancella tutti i breakpoint del sorgente corrente. Il comando è diverso da F9: non cambia soltanto il punto presso il cursore, ma svuota l’insieme dei marcatori. Il contenuto dello Script, la versione semantica e lo SHA-256 salvato non vengono modificati dal comando.

Editor Python con margine privo di breakpoint dopo Ctrl+Shift+F9.
Figura 9. Ctrl+Shift+F9 elimina tutti i punti del documento, senza cambiare il testo.

15. Perché usare il folding

Il folding consente di nascondere temporaneamente le righe interne di funzioni, condizioni e cicli, lasciando in vista i punti principali della struttura. Non equivale a cancellare codice, commentare righe o modificare l’indentazione. Serve soltanto a controllare quanto del sorgente è visibile, per esempio quando si deve individuare rapidamente un’altra funzione.

16. Fold current block dal menu Edit

Posizionare il cursore sulla definizione di una funzione e scegliere Edit → Fold current block. Il corpo viene ripiegato e il margine mostra un chevron chiuso. Nell’esempio, la funzione normalize rimane visibile sulla riga 4, mentre le righe del suo corpo vengono nascoste e la numerazione passa direttamente alle righe successive. Nessun contenuto va perduto.

Editor Python con funzione normalize ripiegata e numerazione fisica che salta alle righe successive.
Figura 10. Fold current block nasconde il corpo della funzione lasciando visibile la riga di definizione.

17. Usare il chevron nel margine

Il simbolo nella terza corsia permette di ripiegare o riaprire un blocco senza passare dal menu. Nel nostro esempio un clic sulla definizione di summarize consente di chiudere anche la seconda funzione. I chevron individuano i punti di folding riconosciuti dal modello del sorgente: non tutti i numeri di riga hanno un simbolo.

Editor Python con entrambe le funzioni normalize e summarize ripiegate tramite il margine.
Figura 11. Il clic sul chevron consente di ripiegare una seconda funzione indipendente.

18. Fold all su tutta la struttura Python

Il comando Edit → Fold all ripiega tutti i blocchi disponibili. Nell’esempio il parser ha identificato sei regioni ripiegabili, comprese strutture annidate; quando il folding è applicato, il quadro generale mostra soltanto le intestazioni più esterne. La vista rimane un documento Python completo: le linee non visibili continuano a esistere nel buffer.

Editor Python dopo Fold all, con righe 4, 14 e 24 e chevron di folding chiusi.
Figura 12. Fold all ripiega i blocchi identificati dal modello Python senza eliminare codice.

19. Unfold all e ritorno alla vista completa

Usare Edit → Unfold all per eliminare tutte le elisioni e ritrovare il codice completo. Le righe nascoste tornano alle stesse posizioni fisiche, senza una nuova revisione né un nuovo salvataggio. Anche quando un breakpoint si trova nel corpo di una funzione ripiegata, esso continua a riferirsi alla sua riga fisica: il folding non sposta il punto.

Editor Python dopo Unfold all, con tutte le istruzioni e numeri di riga nuovamente visibili.
Figura 13. Unfold all ripristina la vista completa dei blocchi del sorgente.

20. Breakpoint e folding sono proprietà differenti

I breakpoint descrivono dove fermare un’eventuale esecuzione; il folding descrive quali parti mostrare nell’editor. È possibile ripiegare una funzione che contiene un breakpoint, oppure aprirla senza cambiare i punti. Non bisogna interpretare un punto non visibile durante il folding come un punto cancellato. Per controllare l’elenco completo si può aprire la scheda Breakpoints.

21. La modifica del codice invalida i vecchi punti

Quando il testo Python viene modificato, l’editor segnala che le posizioni dei breakpoint precedenti sono state cancellate e devono essere riesaminate. Questo comportamento evita che un punto impostato sulla vecchia struttura venga associato automaticamente a un’istruzione diversa dopo l’editing. Nell’esempio è stato aggiunto un commento alla fine del sorgente; il punto precedentemente attivo non è stato mantenuto nel buffer modificato.

Editor Python con messaggio Source edited; breakpoint positions were cleared e nuova riga di commento.
Figura 14. Un cambiamento del sorgente elimina i breakpoint precedenti e segnala che vanno reimpostati.

22. Salvare una revisione diversa dello stesso Script

Dopo la modifica, File → Save aggiorna la revisione registrata e lo SHA-256 del sorgente. I breakpoint sono legati all’identità completa del documento, non soltanto al suo nome: la raccolta della vecchia revisione non viene importata automaticamente in quella nuova. Occorre controllare di nuovo le istruzioni e decidere dove inserire i punti appropriati.

Editor Python con sorgente revisionato e nessun punto importato dalla revisione precedente.
Figura 15. Il salvataggio di una nuova revisione non trasferisce automaticamente i punti del vecchio SHA.

23. Impostare nuovi punti nella revisione aggiornata

Quando il sorgente della nuova revisione è stato analizzato, tornare sulla riga desiderata e premere F9. Il punto appena creato si riferisce alla revisione corrente e al suo SHA-256, non a quella precedente. GX-TXT mantiene separati i riferimenti delle revisioni nella configurazione dei breakpoint; ciò impedisce di trattare come equivalenti due copie del codice che potrebbero avere contenuti diversi.

Editor Python con un nuovo punto rosso alla riga 16 della revisione 2.
Figura 16. Un nuovo F9 crea un breakpoint associato alla revisione salvata più recente.

24. Il significato della freccia gialla

La seconda corsia del margine è riservata alla riga raggiunta dall’esecuzione in debug. A differenza del punto rosso, che rappresenta una condizione impostata dall’utente, la freccia gialla rappresenta una posizione osservata nel programma. Prima di avviare il debugger la freccia non indica alcuna esecuzione attiva: la semplice presenza del codice o di un breakpoint non basta a farla apparire.

25. Verificare un arresto reale su un breakpoint

Per confermare il significato dell’indicatore, è possibile avviare Start Debug su uno Script della Session già salvato e pulito. In un breve esempio reale, il debugger si è inizialmente fermato sulla prima istruzione Python e, dopo Continue, si è arrestato alla riga 16, dove era presente un breakpoint valido. Il margine ha mostrato insieme punto rosso e freccia gialla sullo stesso rigo, con la revisione del sorgente invariata. I comandi di stepping e i pannelli di stato saranno spiegati nella guida dedicata al debugger.

Editor Python realmente in stato PAUSED sul breakpoint 16, freccia gialla e punto rosso sullo stesso rigo.
Figura 17. Durante una vera sospensione Debug, l’indicatore giallo segnala la riga eseguibile raggiunta.

26. I breakpoint non possono cambiare durante un Debug attivo

Quando il debugger è in esecuzione o sospeso, lo snapshot del Job deve restare immutabile. La GUI impedisce di cambiare i breakpoint di quel Job mentre è attivo: per modificare i punti occorre prima terminare la sessione Debug, verificare il codice e prepararne una nuova. Questa protezione mantiene coerenti i marcatori osservati, la revisione registrata e il sorgente realmente eseguito.

27. Stop, stato finale e chiusura del pannello

Il pulsante Stop del debugger arresta il Job gestito dal supervisore. Nel caso illustrato il Job di prova è terminato come CANCELLED, non come una normale elaborazione completata; non ha pubblicato Dataset. Quando il Job raggiunge uno stato terminale, la freccia di esecuzione viene rimossa e i breakpoint tornano gestibili. Chiudere quindi il pannello Debugger prima di proseguire con l’editing. Non è necessario uccidere manualmente processi Python.

28. Tornare al codice e proseguire con il debugger

Terminate le verifiche, utilizzare Unfold all, rimuovere i punti non più necessari e ritornare alla vista del codice con i pannelli superflui chiusi. Nell’editor High Contrast Dark, il margine rimane pronto per un nuovo insieme di breakpoint riferiti alla revisione corretta. Questa guida ha trattato i marcatori e la struttura del sorgente; la successiva esaminerà con maggiore dettaglio Start Debug, Pause, Continue, Step Into, Step Over, Step Out e Stop usando il debugger nativo GX-TXT.

Editor Python nel progetto originale High Contrast Dark dopo la chiusura del Debugger.
Figura 18. Dopo Stop si torna al normale sorgente Python in High Contrast Dark.