Session, Workspace e note scientifiche
Corso Python scientifico in GX-TXT · Modulo 7 · Lezione 38
Una Sessione raccoglie dati e risultati del lavoro. Un Workspace conserva uno stato di lavoro gestito da un provider; una nota può documentare un oggetto senza diventare essa stessa il Dataset. In questa lezione leggiamo la Sessione e associamo una nota a un Dataset sintetico.
Obiettivi
- Leggere il riepilogo della Sessione e l’elenco dei Workspace.
- Pubblicare una serie didattica e documentarla con una nota Markdown.
- Rileggere la nota attraverso l’API pubblica.
- Distinguere identità, contenuto numerico e documentazione.
Esecuzione
Nella Sessione corso_python, importa session_workspace.py, salvalo e
avvialo da Run → Open Script Runner → Run Job. Lo
script crea o aggiorna il proprio Dataset didattico
corso_python_note_sintetiche; la nota viene scritta per
quell’ID.

import numpy as np
from gxtxt import gxtxt_api_call, gxtxt_api_require
for api in ("SESSION_INSPECTION_API_v1@1", "SESSION_WORKSPACE_API_v1@1", "DATASET_PUBLICATION_API_v2@2", "DATASET_NOTES_API_v1@1"):
gxtxt_api_require(api)
info = gxtxt_api_call("SESSION_INSPECTION_API_v1", "summary", [])
workspaces = gxtxt_api_call("SESSION_WORKSPACE_API_v1", "list", [])
dataset = "corso_python_note_sintetiche"
richiesta = {"dataset_id": dataset, "contract": "table.generic", "storage": "csv", "replace_owned": True,
"x_values": np.array([0., 1., 2.]), "y_values": np.array([1., 1.2, 1.1]),
"x_variable": {"variable_id": "tempo", "name": "tempo", "unit": "s"},
"y_variable": {"variable_id": "segnale", "name": "segnale", "unit": "mV"},
"provenance": "Serie sintetica per la lezione sulle note"}
gxtxt_api_call("DATASET_PUBLICATION_API_v2", "publish_series", [richiesta])
nota = "# Serie sintetica\n\nDati didattici, non misure. Tempo in s; segnale in mV.\n"
gxtxt_api_call("DATASET_NOTES_API_v1", "write", [dataset, nota])
letta = gxtxt_api_call("DATASET_NOTES_API_v1", "read", [dataset])
print("Sessione:", info["session_name"])
print("Workspace salvati:", len(workspaces))
print("Dataset annotato:", dataset)
print("Nota riletta:\n", letta)
summary restituisce informazioni sulla Sessione
corrente. list restituisce i Workspace salvati;
nell’esecuzione mostrata la lista è vuota. Un elenco vuoto non significa
che la Sessione non contenga Dataset o grafici: sono risorse con ruoli
distinti.
Lo script pubblica tre punti sintetici, con tempo in secondi e
segnale in millivolt. Poi DATASET_NOTES_API_v1/write
associa una nota Markdown al Dataset e read la rilegge. La
nota dice che i dati sono didattici e ne esplicita le unità.

Una nota su un Dataset e una nota su un Workspace appartengono a
oggetti diversi. Quando esiste un Workspace gestito,
SESSION_WORKSPACE_API_v1 espone anche
note_read e note_write usando il suo ID; qui
non scriviamo una nota di Workspace perché nell’esempio non ce n’è uno
salvato. Usa le API dei rispettivi proprietari, anziché modificare
direttamente file interni della Sessione.
Documentare in modo utile
Una nota può descrivere origine dei dati, metodo, unità, ipotesi e limiti. Non sostituisce lo schema delle variabili né garantisce da sola che un risultato sia corretto. Conserva l’identità del Dataset a cui si riferisce e non attribuire a dati sintetici lo stato di misure.
Esercizio
- Il numero zero di Workspace implica che non ci siano Dataset nella Sessione?
- Quale ID identifica il Dataset annotato?
- Perché rileggere la nota dopo la scrittura?
Soluzione ragionata
- No: Workspace e Dataset sono risorse distinte.
corso_python_note_sintetiche.- Permette di controllare il contenuto restituito dall’API per quell’oggetto, anziché assumere che una stringa preparata in memoria sia stata salvata.
Nella prossima lezione descriveremo una trasformazione prima di applicarla.