Corso Python scientifico in GX-TXT · Modulo 2 · Lezione 11

Una funzione raccoglie istruzioni sotto un nome e può essere richiamata più volte con dati diversi. Questo aiuta a dare un significato ai passaggi, ridurre le ripetizioni e verificare i risultati. Creeremo una funzione che costruisce un riepilogo a partire dalla descrizione di un Dataset GX-TXT.

Obiettivi: definire una funzione con def, passare argomenti, usare valori predefiniti e return, documentare il comportamento e distinguere calcoli locali da effetti sulla Session.

Prerequisiti: variabili, dizionari, condizioni e chiamate alle API delle lezioni precedenti.

Definire e chiamare una funzione

def durata(numero_campioni, intervallo_s):
    return (numero_campioni - 1) * intervallo_s

print(durata(4, 0.5))  # 1.5

def introduce la definizione. numero_campioni e intervallo_s sono parametri: nomi usati nel corpo della funzione. Alla chiamata durata(4, 0.5), i valori 4 e 0.5 sono gli argomenti. Il blocco indentato viene eseguito quando la funzione è chiamata, non mentre la definizione viene letta.

L’esempio descrive quattro istanti sintetici separati da 0,5 s: tra primo e ultimo ci sono tre intervalli, per una durata di 1,5 s. Non sono dati sperimentali. La funzione d’esempio non verifica valori negativi o tipi non validi: un’applicazione reale deve definire e controllare tali precondizioni.

return non è print

return termina la funzione e restituisce un valore al chiamante, che può assegnarlo a un nome o usarlo in un altro calcolo. print mostra testo nell’output ma, da solo, non restituisce quel testo come risultato della funzione. Una funzione che arriva alla fine senza return esplicito restituisce None.

risultato = durata(4, 0.5)
print("Durata (s):", risultato)

Separare calcolo e presentazione permette di riusare il risultato e controllarlo. Per esempio, durata(4, 0.5) == 1.5 è un controllo adatto a questi valori esatti; per risultati floating point generali serve una tolleranza appropriata.

Argomenti posizionali, keyword e default

Gli argomenti possono essere passati per posizione, come sopra, oppure per nome: durata(numero_campioni=4, intervallo_s=0.5). I keyword rendono esplicito il significato e possono essere utili quando ci sono diversi parametri. Una chiamata deve comunque rispettare la firma della funzione.

Un parametro può avere un valore predefinito:

def etichetta(valore, unita="mV"):
    return f"{valore} {unita}"

etichetta(1.2) usa mV; etichetta(1.2, unita="V") usa il testo V. La funzione non converte il numero: cambiare un’etichetta senza convertire il valore non è una conversione fisica. I default sono valutati quando la funzione viene definita; evitare oggetti mutabili come liste vuote condivise quali default, a meno che quel comportamento sia voluto.

Documentazione e ambito locale

Una stringa immediatamente all’inizio del corpo è una docstring e può descrivere scopo, argomenti e risultato. I nomi assegnati dentro una funzione sono normalmente locali a quella chiamata: non diventano automaticamente nomi globali. Preferisci passare dati attraverso parametri e risultati, rendendo esplicite le dipendenze.

Una funzione pura restituisce lo stesso risultato per gli stessi input senza modificare stato esterno osservabile. Una funzione che pubblica un Dataset o cambia la Session ha invece effetti esterni. La distinzione aiuta a progettare controlli: il nostro riepilogo lavora sul dizionario ricevuto e restituisce testo; la chiamata API separata legge metadati da GX-TXT.

Una funzione per un descrittore Dataset

CANONICAL_DATASET_API_v2/describe restituisce i metadati del Dataset richiesto. Il nostro esempio legge il Dataset sintetico creato nella lezione 9 e passa il dizionario alla funzione riepilogo_dataset. La funzione controlla che esistano un identificativo non vuoto e un numero di righe diverso da None; se manca uno dei due, restituisce Descrizione incompleta.

Questo è un controllo minimo, non una validazione completa dello schema: non controlla per esempio che row_count sia un intero non negativo o che le variabili abbiano unità coerenti. Il nome del parametro unita nell’esempio è un’etichetta testuale del conteggio, non un’unità fisica dei dati.

Codice completo

from gxtxt import gxtxt_api_call, gxtxt_api_require

def riepilogo_dataset(descrizione, unita="righe"):
    """Restituisce un riepilogo, senza modificare la Session."""
    identificatore = descrizione.get("dataset_id")
    righe = descrizione.get("row_count")
    if not identificatore or righe is None:
        return "Descrizione incompleta"
    return f"{identificatore}: {righe} {unita}"

gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
dati = gxtxt_api_call("CANONICAL_DATASET_API_v2", "describe", ["corso_python_serie_sintetica"])
print("Dataset:", riepilogo_dataset(dati))
print("Con etichetta esplicita:", riepilogo_dataset(dati, unita="osservazioni"))
print("Esempio incompleto:", riepilogo_dataset({"dataset_id": "prova"}))

Il controllo righe is None è intenzionale: un Dataset con zero righe non è automaticamente una descrizione incompleta. La terza chiamata passa un dizionario sintetico privo di row_count e mostra il ramo di errore previsto.

Funzione di riepilogo Dataset nell'editor Python di GX-TXT.
Funzione di riepilogo Dataset nell'editor Python di GX-TXT.

La funzione è separata dalla chiamata che legge il descrittore nella Session.

Esecuzione

  1. Apri la Session con il Dataset sintetico della lezione 9 e scegli Viewers → Python Scripts.
  2. Importa funzioni_dataset.py, assegna nome e Script ID nello scope session, quindi salva.
  3. Apri Run → Open Script Runner… e premi Run Job.
  4. Nell’output controlla i due riepiloghi del Dataset e la risposta Descrizione incompleta per il dizionario di prova. Nella Session del corso il Dataset ha quattro righe.
Output della funzione con descrittore completo e incompleto.
Output della funzione con descrittore completo e incompleto.

La stessa funzione viene chiamata con l’etichetta predefinita, con una keyword e con un input incompleto.

Errore comune

Se scrivi print(risultato) dentro una funzione ma dimentichi return risultato, la chiamata mostra il valore ma restituisce None. Se poi il chiamante prova a usare quel risultato come numero, il programma non si comporta come previsto. Scegli esplicitamente cosa la funzione deve restituire e cosa, eventualmente, deve mostrare.

Esercizio

Scrivi durata(numero_campioni, intervallo_s=1.0) che restituisca la durata tra il primo e l’ultimo campione. Calcola il risultato per quattro campioni con intervallo predefinito e con intervallo 0.5 s, assumendo almeno un campione.

Soluzione ragionata
def durata(numero_campioni, intervallo_s=1.0):
    return (numero_campioni - 1) * intervallo_s

print(durata(4))                     # 3.0
print(durata(4, intervallo_s=0.5))   # 1.5

Quattro campioni delimitano tre intervalli: con 1 s il risultato è 3 s, con 0,5 s è 1,5 s. Un’implementazione destinata a dati esterni deve controllare l’ipotesi numero_campioni >= 1 e le unità.

Nella prossima lezione esporremo parametri tipizzati nel Runner di GX-TXT.

Scarica gli script del Modulo 02 (ZIP)

#GX-TXT #Python #Script Runner

Altre tappe del progetto

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *