GX-TXT Python Script Workspace: aiuto, accessibilità e risoluzione dei problemi

Il Python Script Workspace integra la modifica dei sorgenti, i comandi per i progetti e l’accesso alle funzioni di esecuzione e debugging. Un uso affidabile dell’interfaccia richiede di sapere dove trovare il manuale, come cercare un comando, come recuperare spazio per il codice e come distinguere un problema di interfaccia da una modifica del sorgente o dello stato scientifico.

Questa guida utilizza i nomi dei controlli esattamente come compaiono nell’interfaccia inglese. Le operazioni di navigazione, ricerca e presentazione non equivalgono a salvare, eseguire uno Script, avviare un Job o pubblicare un Dataset.

1. Riconoscere i tre livelli di lavoro

Nella stessa finestra possono comparire il sorgente Python, i pannelli del progetto e i comandi collegati alla Session. Editor, Script registrato, Job eseguito e Dataset pubblicato sono oggetti distinti: modificare una vista non crea automaticamente nessuno degli altri. Per una prima verifica, aprire uno Script già salvato e controllare che non compaia un indicatore di modifiche non registrate.

2. I tre punti di accesso all’assistenza

Il menu Help del Python Script Workspace contiene Script Bridge help, Viewer manual / Debugger guide… e About…. Il primo presenta le API del client Python; il secondo apre la documentazione consultabile; il terzo mostra informazioni identificative sul modulo. Non confondere questi strumenti con un comando che installa dipendenze o avvia un’analisi.

3. Aprire il menu Help

Selezionare Help nella barra superiore dell’editor. Le voci restano disponibili anche quando il sorgente è in sola lettura o non ha modifiche in sospeso. Questa è la via visiva alternativa alla scorciatoia F1 per consultare la guida del Viewer.

Menu Help originale di Python Script Workspace con le tre voci di assistenza.
Figura 1. Il menu Help espone il manuale del Viewer, la guida Script Bridge e la voce About.

4. Richiamare il manuale con F1

Dare il focus alla finestra Python e premere F1, oppure scegliere Help → Viewer manual / Debugger guide…. Si apre Python Script — User Manual, una finestra separata che può rimanere visibile mentre si lavora sull’editor. Per chiuderla usare Close; il codice aperto non viene modificato.

Finestra reale Python Script User Manual con ricerca e schede Manual e Interactive Tutorial.
Figura 2. Il tasto F1 apre il manuale integrato in una finestra indipendente dall’editor.

5. Manual e Interactive Tutorial

La finestra della guida contiene le schede Manual e Interactive Tutorial, oltre ai controlli di navigazione e ricerca. La scheda Manual presenta il testo di riferimento; la scheda Interactive Tutorial ospita percorsi interattivi quando disponibili per il modulo. La disponibilità di una scheda non implica che ogni esercizio citato da documentazione storica sia operativo nella versione installata.

6. Cercare nel manuale

Digitare una parola o un’espressione nel campo Find e premere Find next o Invio. Il testo trovato viene evidenziato, e lo stato della finestra indica il risultato. Per esempio, cercando F10 focuses si raggiunge direttamente il paragrafo dedicato alla navigazione da tastiera.

Ricerca F10 focuses evidenziata nel manuale GX-TXT con stato Found.
Figura 3. La ricerca del manuale individua e mette in evidenza l’espressione cercata.

7. Quando una parola non si trova

Se non esiste alcuna corrispondenza, il manuale segnala Text not found. e rimuove l’evidenziazione precedente. Provare una parola più breve, una diversa denominazione inglese o una sezione vicina. Questo messaggio non indica un errore del programma né un problema del sorgente Python.

8. Zoom del manuale: distinguere testo e HTML

Nel menu View del manuale compaiono Zoom in, Zoom out e Actual size (100%). Il servizio di zoom è destinato alle pagine HTML e ai tutorial che utilizzano il relativo visualizzatore. Sul testo del manuale mostrato come contenuto Markdown, il comando non costituisce un ingrandimento del font dell’editor Python: non assumere che selezionare Zoom in modifichi i caratteri del codice. Per l’ingrandimento dei caratteri occorre distinguere il visualizzatore della documentazione, le preferenze dell’interfaccia e le impostazioni dei font del desktop.

9. Aprire Script Bridge help

Con Help → Script Bridge help si apre una finestra che elenca le funzioni del client pubblico, con un esempio di importazione da gxtxt. È un riferimento rapido per comprendere i nomi delle chiamate, non un editor alternativo e non un pulsante di esecuzione.

Aiuto originale GX-TXT Python Script Bridge con import gxtxt e funzioni pubbliche.
Figura 4. Script Bridge help descrive le chiamate del client pubblico Python e i prerequisiti delle API.

10. Le funzioni pubbliche richiamate nell’aiuto

L’interfaccia documenta gxtxt_context() per il contesto dell’esecuzione, gxtxt_api_list() per l’elenco delle API dichiarate, gxtxt_api_has(api_id) per verificare la presenza di un’API, gxtxt_api_describe(api_id) per ispezionarne il contratto, gxtxt_api_require(declaration) per richiederne una disponibilità esplicita e gxtxt_api_call(api_id, operation, positional_args) per invocarne un’operazione pubblica.

Prima di chiamare una funzione, controllare l’identificativo completo e la versione del contratto, i parametri e i valori restituiti. L’elenco dei nomi non sostituisce la descrizione dell’API specifica.

11. Esempio informativo senza pubblicazione

Questo esempio è destinato a uno Script eseguito nel contesto appropriato, non alla finestra Help. Le chiamate consultano informazioni disponibili: non pubblicano un Dataset.

# Inspect public client information in the current execution context.
from gxtxt import gxtxt_api_list, gxtxt_context

context = gxtxt_context()
available_apis = gxtxt_api_list()
print("Public API entries:", len(available_apis))
print("Context type:", type(context).__name__)

Il Bridge non isola automaticamente il codice Python dalle risorse del sistema. Verificare sempre la provenienza di uno Script prima di eseguirlo.

12. Cercare nel sorgente Python

Per trovare una variabile o una funzione, selezionare l’editor e premere Ctrl+F, quindi inserire il termine cercato. F3 passa alla corrispondenza successiva e Shift+F3 a quella precedente. Nell’esempio viene individuato measurements: il testo viene evidenziato, ma il sorgente salvato resta invariato.

Editor High Contrast Dark con ricerca del termine measurements nel sorgente Python.
Figura 5. Find e Find next evidenziano una corrispondenza senza cambiare il codice salvato.

13. Ricerca nel codice e ricerca nella documentazione

Il campo Find del Viewer e quello del manuale sono separati. Se la ricerca sembra non funzionare, verificare quale finestra ha il focus e se si sta lavorando in una nota Markdown anziché nel codice Python. Un risultato assente in un campo non dimostra che la parola manchi dall’intero progetto.

14. Spostarsi a una riga e leggere l’indicatore

Con Ctrl+G si apre Go to line…. Inserire un numero intero positivo per portare il cursore alla riga fisica corrispondente; Cancel chiude senza spostamenti. I numeri nel margine appartengono al sorgente corrente, non necessariamente al file di una scheda storica o di un helper diverso.

15. Navigazione da tastiera essenziale

Tasto o combinazioneAzione
F1Apre il manuale del Viewer
F10Porta alla navigazione dei menu
Alt+F, Alt+E, Alt+V, Alt+HAccede ai relativi menu, secondo il focus
Ctrl+FCerca nel contesto di modifica corrente
F3 / Shift+F3Risultato successivo / precedente
Ctrl+GGo to line…
Ctrl+SSalva il sorgente modificato
EscapeChiude o lascia il controllo di ricerca, secondo il contesto

I comandi vengono gestiti dal widget che possiede il focus. Evitare di premere scorciatoie di modifica quando è attiva una finestra di dialogo o una scheda in sola lettura.

16. Ritrovare i comandi di layout nel menu View

Il menu View include Script Explorer / Registered scripts, GX-TXT Bridge Snippets, Focus source / restore panes e Reset editor layout. Sono strumenti di presentazione: aprono, chiudono o riposizionano componenti della finestra. È opportuno esaminare il menu prima di presumere che un pannello mancante sia stato eliminato dal progetto.

Menu View originale con Focus source restore panes e Reset editor layout.
Figura 6. Dal menu View si possono ripristinare i pannelli o dedicare lo spazio all’editor.

17. Ripristinare un layout disordinato

Se l’editor appare troppo stretto o alcuni pannelli non sono più facilmente raggiungibili, selezionare View → Reset editor layout. Il comando ripristina il layout laterale con Explorer e Snippets e le proporzioni principali dei divisori. Le righe opzionali Script properties, Parameters, Version e Additional required APIs conservano preferenze indipendenti: Reset non implica che vengano tutte mostrate.

Interfaccia Python dopo Reset editor layout con Explorer, sorgente centrale e pannello Snippets.
Figura 7. Reset editor layout riapre Explorer e Snippets; l’editor viene temporaneamente ristretto.

18. Dedicare più spazio al codice

Quando non servono strumenti laterali, selezionare View → Focus source / restore panes. Il comando nasconde temporaneamente i pannelli laterali e amplia il sorgente. Usarlo nuovamente per ripristinare i pannelli precedentemente memorizzati. Questa operazione non esegue Python e non salva uno Script.

Editor Python originale con sorgente High Contrast Dark dopo Focus source.
Figura 8. Focus source riduce l’affollamento e restituisce spazio al testo del programma.

19. Riattivare un singolo pannello

Se serve soltanto l’elenco dei file, attivare Script Explorer / Registered scripts; se occorrono i riferimenti rapidi, attivare GX-TXT Bridge Snippets. Tenere gli altri pannelli chiusi durante la modifica del codice evita di comprimere inutilmente l’area di lavoro. Aprire Debugger, Call Stack o Variables / Locals solo quando si segue effettivamente un Job di debugging.

20. Contrasto reale del sorgente

Il tema High Contrast Dark applica all’area di codice un fondo nero e testo principale bianco, con evidenziazioni sintattiche specifiche. Le barre, i menu e alcuni dialoghi Tk/ttk possono rimanere chiari: il tema del sorgente non ricolora necessariamente tutta la GUI. In Configuration → Appearance, la preferenza Source color theme governa la tavolozza del codice.

21. Dimensione dei caratteri e leggibilità

L’editor utilizza un font monospaziato della piattaforma. Prima di aumentare il numero di pannelli o ridurre la finestra, verificare se le righe, il cursore e le parentesi restano leggibili. Un comando di zoom presente nel manuale non è una prova che lo stesso comando ingrandisca il sorgente. Se servono caratteri più grandi, considerare le impostazioni font del desktop e controllare il risultato reale, senza confonderle con la palette di colore del codice.

22. Quando una voce è disabilitata

Una voce grigia può dipendere da tipo di documento, assenza di una Session, stato del debugger, selezione corrente o scheda storica in sola lettura. Ad esempio, i comandi relativi alle Notes possono richiedere una nota aperta; alcune azioni del Runner richiedono una revisione Script registrata; i comandi di esecuzione diventano limitati con sorgenti modificati o riferimenti obsoleti. Verificare prima il contesto anziché cercare di forzare il controllo.

23. Modifiche non salvate: non perdere il sorgente

Un buffer modificato non coincide con la revisione presente nel Registry. Prima di chiudere una scheda, distinguere Save, No e Cancel nel dialogo per il sorgente non salvato. No scarta il buffer corrente; Cancel annulla la chiusura. In presenza di un Project multifile, controllare quale scheda è sporca e se occorre Save All. Una vista storica aperta da un Job può invece essere intenzionalmente read_only.

24. Problemi di Save, scope e revisione

Se il salvataggio non riesce, controllare User/Session scope, identificativo, tipo di sorgente, campi obbligatori e revisione che si sta modificando. Due Script con lo stesso nome breve ma proprietari differenti possono essere distinti; una revisione registrata non si sostituisce implicitamente a un’altra. Conservare il testo modificato prima di tentare una nuova registrazione o una copia.

25. Problemi di Run e parametri

Aprire Script Runner non crea un Job: prima controllare lo Script salvato, il contesto Session e il riepilogo di Validate review. I parametri dichiarati nel codice hanno tipi, vincoli e valori di default; un Dataset di parametri può appartenere a una revisione differente. Un errore di validazione non va aggirato eseguendo uno Script non controllato.

26. Dataset e output: verificare cosa è stato creato

Il completamento di un Job e la presenza di testo su stdout non dimostrano che esista un Dataset scientifico. Distinguere fra stdout/stderr, documenti testuali pubblicati e Dataset numerici con schema, unità e provenienza. Se un input Dataset non viene accettato, controllare il namespace, l’identificativo e la revisione selezionata, quindi ripetere la validazione prima dell’esecuzione.

27. Debugging e problemi ricorrenti

Breakpoint, Pause, Step Into/Over/Out e Stop dipendono dallo stato dell’esecuzione nativa. Le condizioni COMPLETED, FAILED e CANCELLED non sono intercambiabili. Per un’eccezione Python leggere la traccia e il numero di riga in Program stderr; per diagnosi del sistema distinguere il log diagnostico; per uno Script eseguito in passato consultare la copia immutabile associata al Job. Evitare modifiche del sorgente durante una Session di debug in pausa.

28. Sequenza pratica di recupero

Se un comando non produce il risultato atteso, controllare prima il focus, poi la scheda attiva, il contenuto non salvato, il tipo di Session e lo stato del Job. Per l’interfaccia usare Help/F1, Find e View; per l’esecuzione aprire il Runner e convalidare i dati; per l’analisi di un risultato esaminare Job Details e la pubblicazione canonica. Eventuali istruzioni storiche su Viewer separati non costituiscono una procedura verificata per questa versione.

Terminata la consultazione, chiudere le finestre di aiuto non necessarie e tornare al sorgente in modalità High Contrast Dark con spazio di modifica ampio.

Python Script Workspace con sorgente Python leggibile e pannelli non necessari nascosti.
Figura 9. Al termine dell’assistenza si può lasciare l’editor nella configurazione concentrata sul codice.