GX-TXT Python Script Workspace: gli snippet del Bridge e la guida integrata
Python Script Workspace offre un repertorio di esempi per il client pubblico Python di GX-TXT. Il pannello GX-TXT Bridge Snippets inserisce nel sorgente istruzioni per leggere il contesto di esecuzione, scoprire le API disponibili, dichiarare un requisito e preparare una chiamata a un’operazione documentata.
Gli snippet sono modelli di codice, non pulsanti di esecuzione. Possono essere inseriti e modificati senza avviare alcun Job. Esamineremo anche Script Bridge help, il manuale integrato accessibile con F1 e la finestra About.
1. Che cosa significa Python Script Bridge
Il Bridge è il collegamento pubblico fra un programma Python eseguito da GX-TXT e le API che il framework rende disponibili agli Script scientifici.
Da Python si importa il package pubblico gxtxt. Non occorre richiamare direttamente procedure Tcl, file interni del CORE o servizi privati. Il client consulta il contesto e trasmette richieste alle operazioni esposte dai provider.
2. Trovare il pannello degli snippet
Aprire Viewers → Python Scripts e scegliere View → GX-TXT Bridge Snippets. Questa voce mostra o nasconde il pannello laterale dedicato.
Sono presenti il selettore degli esempi, il pulsante Insert e un breve riferimento alle funzioni disponibili. L’area principale continua a essere un editor Python con sintassi evidenziata.
3. Lasciare spazio al codice
Mantenere chiusi Explorer, Debugger, Parameters e altri pannelli non necessari. Aprire soltanto GX-TXT Bridge Snippets quando serve scegliere un esempio.
Una volta inserito il frammento, nascondere il pannello con la stessa voce di View per recuperare larghezza. Questo non modifica il codice già inserito.
4. Le cinque scelte del selettore
Il selettore offre Context, Discover APIs, Require API, Describe API e Call API. Ogni scelta prepara un esempio riguardante una funzione pubblica.

Scegliere una voce e premere Insert. Il testo viene aggiunto alla posizione del cursore: prima di procedere, verificare quale scheda e quale punto di inserimento siano attivi.
5. Context: inserire l’accesso al contesto
Con Context → Insert compare un frammento che importa gxtxt_context, richiama la funzione e visualizza il risultato con print.

La comparsa di quelle righe nell’editor non crea un contesto di Job. La funzione viene valutata quando il programma è eseguito da GX-TXT con un Bridge attivo.
6. Il risultato di gxtxt_context()
La funzione pubblica gxtxt_context() non richiede argomenti. Durante un’esecuzione gestita restituisce informazioni sul contesto del Job.
Tra i dati documentati figurano gli alias degli input, i parametri tipizzati e la directory di output gestita dal framework, quando pertinenti. Il programma deve utilizzare i valori effettivamente ammessi, senza inventare percorsi interni o supporre la presenza di Dataset non dichiarati.
7. Discover APIs: ottenere l’elenco
Con Discover APIs → Insert il Workspace inserisce un esempio che importa gxtxt_api_list e percorre gli elementi restituiti.

Il frammento servirà a conoscere le API pubbliche registrate durante un’esecuzione gestita, invece di basarsi su elenchi di un’altra versione.
8. Interpretare gxtxt_api_list()
gxtxt_api_list() non richiede argomenti e chiede al Bridge le API pubbliche registrate. La risposta è consultabile da Python.
La presenza di un’API nell’elenco non garantisce che ogni operazione sia utilizzabile con qualsiasi argomento. Occorre verificare il descrittore, le capability e i vincoli del provider.
9. Verificare API e operazioni
gxtxt_api_has(api_id) riceve un identificativo e verifica se l’API è registrata nel Bridge. gxtxt_api_has_operation(api_id, operation) controlla invece una specifica operazione.
Questi controlli sono utili prima di formulare una richiesta, ma non eseguono un’analisi scientifica né sostituiscono la validazione degli input richiesti.
10. Require API: dichiarare un requisito
La scelta Require API → Insert aggiunge un esempio che chiama gxtxt_api_require con la dichiarazione SOME_PUBLIC_API_v1@1.

SOME_PUBLIC_API_v1 è un segnaposto e non identifica un provider garantito. Sostituirlo con un’API reale, verificandone la versione e il contratto pubblico.
11. Il contratto di gxtxt_api_require()
gxtxt_api_require(requirements) accetta una dichiarazione, un dizionario di requisiti o una lista di dichiarazioni. La stringa può specificare ID, versione e, quando necessario, provider o capability.
Per esempio CANONICAL_DATASET_API_v2@2 richiede il contratto Canonical Dataset versione 2. Una richiesta non soddisfatta può generare un errore del Bridge. La funzione non installa pacchetti.
12. Requisiti e registrazione dello Script
Le dichiarazioni di requisito e il campo Additional required APIs riguardano l’ammissione delle API durante una futura esecuzione. Sono controlli distinti dall’inserimento del testo.
Aggiungere gxtxt_api_require() nel buffer non salva automaticamente una revisione, non avvia il Runner e non concede accesso a funzioni private del CORE.
13. Describe API: leggere il descrittore
Describe API → Insert prepara un esempio che importa gxtxt_api_describe, utilizza un ID illustrativo e assegna il risultato a una variabile.

Sostituire il segnaposto con l’identificativo di una vera API pubblica. Il descrittore è il riferimento iniziale per conoscere versione, provider e operazioni.
14. Il risultato di gxtxt_api_describe()
gxtxt_api_describe(api_id) riceve l’ID dell’API e restituisce il descrittore strutturato che il Bridge rende disponibile.
Le informazioni possono riguardare provider, versioni, capability, nomi delle operazioni e argomenti. Per significato scientifico, unità fisiche e struttura dei risultati occorre leggere anche il manuale dell’API specifica.
15. Un Bridge generico per servizi differenti
Il client Python non reimplementa ogni operazione scientifica: usa le richieste dei provider registrati. La stessa funzione di chiamata può interagire con servizi differenti.
Lettura di Dataset, gestione di progressi o costruzione di grafici hanno però contratti separati. Non esiste un insieme universale di parametri valido per tutti i servizi.
16. Call API: preparare una chiamata
Con Call API → Insert compare un esempio che utilizza gxtxt_api_call con API, operazione e lista di argomenti posizionali.

Le parole SOME_PUBLIC_API_v1, documented_operation e request sono segnaposto: bisogna sostituirle o definire le variabili necessarie prima di eseguire il codice.
17. Il contratto di gxtxt_api_call()
La firma pubblica è gxtxt_api_call(api_id, operation, args=None). I primi due parametri identificano API e operazione. Il terzo è una lista o tupla Python con argomenti nell’ordine previsto dal servizio.
Per operazioni senza argomenti si può passare []. Il risultato dipende dal provider. API non registrate, operazioni non ammesse, parametri errati o errori del provider possono generare GXTXTBridgeError con un identificativo diagnostico.
18. Un esempio di API pubblica documentata
Il client Python documenta una richiesta di elenco per CANONICAL_DATASET_API_v2. In un Job GX-TXT che ammetta tale API, un modello essenziale è:
# Example for a managed GX-TXT Python Job; not executed here.
from gxtxt import gxtxt_api_require, gxtxt_api_call
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
datasets = gxtxt_api_call("CANONICAL_DATASET_API_v2", "list", [])
print(datasets)
Questo è un esempio d’interfaccia, non il risultato di un esperimento. Per utilizzarlo occorrono un contesto gestito attivo e l’effettiva disponibilità del provider.
19. Sostituire correttamente i segnaposto
Prima di riutilizzare uno snippet, controllare gli identificativi illustrativi e le variabili. Il modello gxtxt_api_call(..., [request]) presuppone che request sia stata definita con la struttura richiesta dal contratto dell’operazione.
Un inserimento non completa il programma. Bisogna verificare dati, unità, dimensioni, limiti e significato dei risultati.
20. Insert è una modifica locale
Insert scrive nel buffer della scheda attiva. Non equivale a Save, non registra una revisione nel Registry e non avvia un Job.
Se il frammento viene inserito nel punto sbagliato, Ctrl+Z ne annulla la modifica; Ctrl+Y permette il ripristino. La cronologia locale dell’editor è indipendente dai Job scientifici.
21. Nascondere il pannello dopo l’inserimento
Quando il codice è stato preparato, utilizzare nuovamente View → GX-TXT Bridge Snippets per nascondere l’assistente.
Il sorgente resta modificabile, con maggiore larghezza disponibile. Il pannello non deve rimanere aperto durante la stesura del programma.
22. Script Bridge help
Il comando Help → Script Bridge help apre una finestra separata e di sola lettura con un riferimento alle funzioni pubbliche.

La guida rimanda al documento Python Script Client v1 e avverte che il Bridge non è una sandbox: il programma Python conserva le capacità normalmente consentite dall’ambiente configurato.
23. Altre funzioni del client pubblico
Il riferimento include anche gxtxt_bridge_info(), che consulta le informazioni sul Bridge attivo, oltre a gxtxt_api_has() e gxtxt_api_has_operation().
Il client documenta inoltre le callback e le dichiarazioni dei parametri tipizzati. Queste funzionalità hanno contratti specifici: non devono essere confuse con gli esempi di inserimento degli snippet.
24. Il manuale integrato con F1
Premendo F1 nel Python Script Workspace si apre Python Script — User Manual, con le schede Manual e Interactive Tutorial e un campo Find.
Il pulsante Find next cerca nel manuale. Inserendo Bridge, il risultato viene evidenziato.

Il manuale può coprire funzioni più ampie del lavoro corrente. Per ogni procedura è opportuno verificare che i relativi comandi siano realmente disponibili nella propria installazione.
25. About: conoscere la versione installata
Con Help → About… si apre il dialogo informativo sul modulo. Mostra il nome Python Script, l’identificativo analysis.python_script, il Viewer python_script_editor e la versione.

La versione qui illustrata è 1.6.3. About riporta anche alcuni riferimenti API del modulo; non è però l’elenco dinamico completo delle operazioni disponibili in un Job.
26. Il nome storico del Bridge
Il riferimento mostra l’ID storico OCTAVE_SCRIPT_BRIDGE_API_v1. Il nome non significa che gli Script Python usino la sintassi di GNU Octave: il Bridge e il trasporto dei provider sono condivisi fra i due linguaggi.
Nel programma Python si continuano a usare from gxtxt import ..., normali oggetti Python e liste o tuple di argomenti. Il documento di riferimento resta Python Script Client v1.
27. Tabella delle funzioni principali
| Funzione pubblica Python | Argomenti essenziali | Scopo |
|---|---|---|
gxtxt_context() | Nessuno | Leggere il contesto del Job |
gxtxt_bridge_info() | Nessuno | Leggere le informazioni sul Bridge |
gxtxt_api_list() | Nessuno | Elencare le API registrate |
gxtxt_api_has(api_id) | Identificativo API | Verificare un’API registrata |
gxtxt_api_describe(api_id) | Identificativo API | Consultare il descrittore |
gxtxt_api_has_operation(api_id, operation) | ID e operazione | Verificare una specifica operazione |
gxtxt_api_require(requirements) | Requisito o lista di requisiti | Controllare i requisiti API |
gxtxt_api_call(api_id, operation, args=None) | API, operazione e argomenti posizionali | Chiamare un’operazione documentata |
Le funzioni elencate sono presenti nel client pubblico della versione illustrata. Restituzioni scientifiche reali e accesso ai provider richiedono un contesto gestito e i rispettivi contratti.
28. Riepilogo
GX-TXT Bridge Snippets facilita la scrittura di esempi Python; Script Bridge help, F1 e About permettono di consultare i riferimenti e conoscere la versione installata.
Insert non è Run e uno snippet non sostituisce il contratto di un’API. Prima di un’esecuzione, controllare segnaposto, input, operazioni documentate e requisiti del Bridge.
Il prossimo capitolo approfondirà la disposizione dei pannelli, Focus source / restore panes e la leggibilità dell’editor.