GX-TXT Python Script Workspace: aprire l’editor e distinguere User e Session
Python Script Workspace è l’ambiente di GX-TXT dedicato alla preparazione e alla gestione di sorgenti Python. In questa guida apriamo il Viewer dalla finestra principale, riconosciamo lo stato iniziale dell’editor e distinguiamo un documento User da uno destinato alla Session. Non occorre avviare alcun calcolo.
1. Che cosa apre Python Script Workspace
Il Viewer offre un editor Python con evidenziazione della sintassi, schede sorgente, campi identificativi, strumenti di navigazione e accesso alla documentazione delle API pubbliche GX-TXT. È l’ambiente in cui si prepara il codice: non è, da solo, un risultato scientifico.
Lavorare sul sorgente, registrare uno Script, eseguire un Job e pubblicare un Dataset sono operazioni differenti. La loro separazione è utile già al primo avvio.
2. Aprire il Viewer dalla finestra principale
Nella finestra GX-TXT scegliere la scheda Viewers, individuare la categoria Scientific Scripting e selezionare il riquadro Python Scripts. Se i Viewer disponibili sono numerosi, il campo Search aiuta a trovare il riquadro corretto.
Il pulsante apre la finestra denominata Python Script Workspace. Se il Viewer è già aperto, richiamarlo dallo stesso riquadro porta in primo piano la finestra esistente, senza richiedere un secondo ambiente.

3. Prima di iniziare: serve una Session?
Per aprire il Viewer e preparare un sorgente User non è necessaria una Session. È quindi possibile leggere i controlli e comporre una bozza anche quando la finestra principale indica che non vi è una Session aperta.
Per registrare uno Script con Scope session e per eseguire attività scientifiche occorre invece aprire la Session di destinazione. La presenza del Viewer non equivale a un collegamento automatico a una Session.
4. La schermata generale del Workspace
La finestra contiene una barra di menu nella parte superiore, il pannello Registered Python scripts, un’area centrale con l’editor, i campi identificativi e il pannello GX-TXT bridge snippets.
La schermata che segue apre volutamente i pannelli per mostrarne la posizione. Non è la configurazione più comoda quando si deve scrivere codice: dopo aver compreso il layout conviene recuperare spazio nell’editor.

5. A cosa servono i pannelli
Registered Python scripts presenta gli Script registrati disponibili nel contesto corrente; un elenco vuoto non significa che l’editor non possa aprirsi. L’area centrale ospita le schede dei sorgenti e il testo modificabile.
Il riquadro GX-TXT bridge snippets offre esempi di utilizzo del client pubblico GX-TXT. Uno snippet è testo di supporto: la sua visualizzazione non avvia un Job e non chiama automaticamente un’API.
6. I sei menu della finestra
La barra superiore contiene File, Edit, Project, View, Run e Help. I primi tre riguardano soprattutto il lavoro sui sorgenti, sulle proprietà e sui progetti; View permette di mostrare o nascondere i pannelli, Run ospita gli ingressi ai flussi di esecuzione e Help rende disponibile il manuale.
Un comando visibile non è necessariamente eseguibile nello stato corrente. Per esempio, una voce può essere disabilitata finché manca uno Script registrato. I menu e le scorciatoie saranno esaminati in dettaglio nel capitolo successivo.
7. Il primo documento: untitled.py
All’apertura iniziale compare normalmente una scheda untitled.py. Si tratta di una bozza con alcune righe Python predisposte dal Viewer: non è un file scientifico già eseguito e non possiede automaticamente un’identità registrata.
Il nome descrittivo iniziale è Untitled script e la versione mostrata è 1.0.0. Prima di conservare uno Script reale, questi campi dovranno essere completati consapevolmente.
8. Il codice iniziale è un esempio, non un risultato
La scheda iniziale contiene il seguente schema Python, utile per riconoscere il client del framework:
# GX-TXT Python Script
from gxtxt import gxtxt_context, gxtxt_api_list, gxtxt_api_call
ctx = gxtxt_context()
print(ctx)
print(gxtxt_api_list())
Questo testo viene mostrato nell’editor ma non viene eseguito all’apertura del Viewer. Le righe print non producono alcun risultato finché non viene preparata ed eseguita una vera attività di Script nel contesto GX-TXT.
9. Il significato delle funzioni del client Python
gxtxt_context() restituisce il contesto della specifica esecuzione gestita da GX-TXT, comprendente gli input e le informazioni di invocazione disponibili. Non è una richiesta da eseguire manualmente nell’editor per scoprire i Dataset.
gxtxt_api_list() permette di interrogare le API pubbliche disponibili nel Bridge attivo. gxtxt_api_call(api_id, operation, args) invoca un’operazione pubblica registrata, usando un elenco o una tupla Python di argomenti posizionali. Per conoscerne i contratti è necessario consultare la documentazione dell’API specifica.
Il Bridge ha senso nel contesto di una vera esecuzione gestita. Un’importazione visibile nel codice di esempio non certifica, da sola, che la chiamata sia stata effettuata.
10. Evidenziazione sintattica e linee numerate
L’editor riconosce elementi Python come parole chiave, stringhe, commenti e nomi delle funzioni. I numeri delle righe aiutano a individuare una posizione, mentre lo stato in basso riporta la riga e la colonna correnti.
Il testo è modificabile, ma le operazioni di scrittura, ricerca, annullamento e salvataggio saranno documentate nei rispettivi capitoli. Per questa prima visita è sufficiente identificare l’area sorgente senza cambiare il codice.
11. Dare priorità al codice con Focus source
Per lavorare con più spazio usare View → Focus source / restore panes. Il comando riduce l’affollamento nascondendo i riquadri laterali che non servono all’attività corrente.
Quando occorre consultare proprietà o strumenti, utilizzare lo stesso menu View per farli ricomparire. Non è necessario tenere continuamente aperti Explorer, snippets e pannelli secondari mentre si modifica il codice.

12. L’aspetto High Contrast Dark dell’editor
La superficie del codice può utilizzare il tema nativo High Contrast Dark: il fondo dell’editor è nero, il testo ordinario chiaro e gli elementi sintattici colorati. Questo rende più evidente la separazione fra codice e altri controlli.
Il tema scuro riguarda la superficie Source, non necessariamente tutta la finestra Tk. È quindi normale che menu, etichette e pannelli esterni conservino un aspetto chiaro. Non serve modificare o ricolorare gli screenshot per ottenere una falsa finestra uniformemente scura.
13. Scope: il significato del campo
Il campo Scope indica l’ambito nel quale uno Script potrà essere registrato. Le due scelte dell’editor sono user e session.
Uno Script User appartiene alla raccolta dell’utente e può essere preparato senza una Session scientifica aperta. Uno Script Session appartiene invece a una specifica Session e ne segue l’identità. Un documento ancora privo di Script ID non diventa automaticamente registrato solo perché è selezionato uno Scope.
14. Stato User senza Session aperta
Quando si avvia il Viewer senza una Session, un nuovo documento assume normalmente Scope = user. Il campo Script ID è inizialmente vuoto e il sorgente non è ancora registrato.
La schermata mostra anche il nome e la versione della bozza. Questi valori rappresentano la preparazione di un possibile Script, non un file già salvato nella raccolta.

15. Nome, ID e versione non sono intercambiabili
Script ID è l’identificativo stabile che verrà usato per distinguere lo Script registrato. Name è il nome descrittivo destinato all’utente. Version descrive la versione semantica del sorgente.
Gli altri campi permettono di associare descrizione, API richieste e parametri dichiarati. Conviene scegliere ID e metadati coerenti prima di salvare. Questa guida non effettua ancora un salvataggio: l’identità, le revisioni e i controlli sui duplicati saranno verificati nei capitoli dedicati.
16. Che cosa significa unsaved nella barra di stato
La barra inferiore può mostrare unsaved, una revisione iniziale e SHA-256 pending. La voce unsaved indica che non è stata ancora stabilita l’identità registrata della bozza; pending significa che non esiste ancora l’hash del sorgente registrato.
La stessa barra può riportare lo stato locale saved quando il buffer non contiene modifiche rispetto alla propria base iniziale. Questo non significa che sia stato pubblicato un Dataset o che esista già uno Script registrato: lo stato locale dell’editor e la persistenza nel Registry sono due informazioni differenti.
17. Quando si apre una Session scientifica
Dalla finestra principale GX-TXT aprire la Session nella quale si intende lavorare, usando il normale percorso di gestione delle Session. Prima di proseguire assicurarsi di aver selezionato quella corretta.
Una Session contiene il proprio contesto di lavoro, ma la sua apertura non esegue il codice presente nell’editor e non trasferisce per implicito uno Script User nella raccolta Session.
18. Riaprire il Viewer nella Session desiderata
Se Python Script Workspace era aperto con un’altra Session oppure senza Session, chiudere la bozza non modificata e riaprire il Viewer dalla scheda Viewers dopo aver scelto la Session desiderata. Questo evita di scambiare il contesto precedente con quello nuovo.
Se sono presenti modifiche non salvate, è opportuno conservarle o esportarle con il procedimento appropriato prima di cambiare contesto. L’editor protegge le operazioni Session-scope con un controllo sul ciclo di vita della Session, proprio per impedire un salvataggio nella Session sbagliata.
19. La nuova bozza assume Scope session
Con una Session attiva, un nuovo documento appena aperto assume normalmente Scope = session. Rimangono visibili l’editor Python, untitled.py, il nome descrittivo e la versione iniziale.
Il campo Script ID può essere ancora vuoto: Scope session non equivale a Save. Si tratta soltanto di una bozza predisposta per la Session corrente.

20. Confronto User e Session
| Caratteristica | Scope user | Scope session |
|---|---|---|
| Session già aperta per preparare una nuova bozza | Non necessaria | Necessaria per la registrazione Session |
| Proprietà dello Script registrato | Raccolta User | Session corrente |
| ID registrato al semplice avvio | No | No |
| Esecuzione automatica all’apertura dell’editor | No | No |
| Riferimento alla Session | Non implicito | Esplicito per lo Script registrato |
La scelta dello Scope non copia, trasferisce o assegna da sola uno Script: le operazioni di registrazione e gestione delle revisioni richiedono comandi dedicati.
21. Editor, Script registrato, Job e Dataset
È utile distinguere quattro momenti: il sorgente nell’editor è testo modificabile; lo Script registrato ha ID, Scope e revisione; il Job rappresenta una specifica esecuzione avviata esplicitamente; un eventuale Dataset è un risultato pubblicato con il proprio contratto.
Un sorgente Python non si trasforma automaticamente in un Dataset. Anche un messaggio stampato a video da un futuro Job non è, di per sé, una tabella canonica.
22. Dove trovare aiuto
Il menu Help consente di aprire il manuale del Viewer tramite F1 e la guida Script Bridge help. Il riferimento del Bridge presenta le funzioni client disponibili per interrogare e invocare le API pubbliche.
Prima di usare un’operazione scientifica verificare il suo identificativo, la versione effettiva, gli argomenti ammessi e il contratto del risultato. Evitare di dedurre la presenza di funzioni operative dal solo nome di un menu.
23. Operazioni da rimandare ai capitoli dedicati
Questa prima apertura non richiede modifiche al codice, salvataggi, installazione di librerie o invio di Job. I capitoli successivi affronteranno i menu e le scorciatoie, l’identità degli Script, il salvataggio, l’importazione di file Python, i progetti, il Runner e il debugger.
Per il lavoro scientifico useremo Script di esempio e Session controllate, mantenendo sempre distinti testo sorgente, registrazione, esecuzione e pubblicazione dei risultati.
24. Riepilogo
Python Script Workspace si apre da Viewers → Python Scripts anche senza Session. Un nuovo sorgente parte come bozza, normalmente user senza Session e session quando viene riaperto nel contesto di una Session attiva.
L’editor High Contrast Dark permette di lavorare sul codice con i pannelli opzionali chiusi. Una corretta comprensione di Scope, Script ID e stato unsaved è il prerequisito per utilizzare con sicurezza gli strumenti di salvataggio e di esecuzione che vedremo successivamente.