Funzioni, argomenti e ritorni
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.

La funzione è separata dalla chiamata che legge il descrittore nella Session.
Esecuzione
- Apri la Session con il Dataset sintetico della lezione 9 e scegli Viewers → Python Scripts.
- Importa
funzioni_dataset.py, assegna nome e Script ID nello scopesession, quindi salva. - Apri Run → Open Script Runner… e premi Run Job.
- Nell’output controlla i due riepiloghi del Dataset e la risposta
Descrizione incompletaper il dizionario di prova. Nella Session del corso il Dataset ha quattro righe.

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.5Quattro 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.