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.

Python Script Workspace con pannello GX-TXT Bridge Snippets, selettore Context, pulsante Insert e sorgente scuro
Figura 1. Il pannello GX-TXT Bridge Snippets presenta le cinque scelte disponibili accanto all’editor High Contrast Dark.

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.

Editor GX-TXT Python con snippet Context e codice da gxtxt import gxtxt_context, senza esecuzione dello Script
Figura 2. Insert con Context aggiunge le istruzioni Python per leggere il contesto di un futuro Job gestito.

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.

Python Script Workspace con snippet Discover APIs, gxtxt_api_list e pannello autentico GX-TXT Bridge Snippets
Figura 3. Discover APIs inserisce il modello con gxtxt_api_list per consultare le API registrate durante un’esecuzione gestita.

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.

Snippet Python Require API con gxtxt_api_require e riferimento illustrativo SOME_PUBLIC_API_v1 versione 1
Figura 4. Require API inserisce una dichiarazione di requisito; SOME_PUBLIC_API_v1 è un segnaposto da sostituire.

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.

Editor Python con snippet Describe API, dichiarazione gxtxt_api_describe e modello senza esecuzione
Figura 5. Describe API inserisce un esempio per leggere il descrittore di una vera API pubblica tramite gxtxt_api_describe.

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.

Editor Python mostra snippet Call API con gxtxt_api_call, documented_operation e lista di argomenti
Figura 6. Call API presenta gxtxt_api_call con API, operazione e lista posizionale di argomenti: i segnaposto richiedono adattamento.

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.

Finestra reale GX-TXT Python Script Bridge con elenco gxtxt_context gxtxt_api_list e funzioni pubbliche
Figura 7. Help → Script Bridge help elenca le funzioni pubbliche del client e identifica il Bridge condiviso fra Python e Octave.

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.

Finestra Python Script User Manual aperta con F1, campo Find impostato su Bridge e risultato evidenziato
Figura 8. Il manuale integrato aperto con F1 permette una ricerca: Find localizza il termine Bridge nel testo.

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.

Dialogo About Module di GX-TXT con analysis.python_script, Python Script Workspace versione 1.6.3 e API elencate
Figura 9. Help → About mostra il modulo Python Script, il Viewer e la versione installata 1.6.3.

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 PythonArgomenti essenzialiScopo
gxtxt_context()NessunoLeggere il contesto del Job
gxtxt_bridge_info()NessunoLeggere le informazioni sul Bridge
gxtxt_api_list()NessunoElencare le API registrate
gxtxt_api_has(api_id)Identificativo APIVerificare un’API registrata
gxtxt_api_describe(api_id)Identificativo APIConsultare il descrittore
gxtxt_api_has_operation(api_id, operation)ID e operazioneVerificare una specifica operazione
gxtxt_api_require(requirements)Requisito o lista di requisitiControllare i requisiti API
gxtxt_api_call(api_id, operation, args=None)API, operazione e argomenti posizionaliChiamare 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.

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.