In Python, la risoluzione della scoping delle variabili viene eseguita staticamente durante la fase di compilazione piuttosto che dinamicamente durante l'esecuzione. Quando il compilatore CPython incontra una definizione di funzione, attraversa l'albero di sintassi astratta per costruire una tabella dei simboli che categorizza ogni nome come locale, globale o variabile cella. Se il compilatore rileva qualsiasi operazione di binding, come assegnazione, assegnazione aumentata o importazione, per un nome in qualsiasi punto del corpo della funzione, segna quel nome come una variabile locale per l'intero ambito. Questo design consente alla macchina virtuale di utilizzare opcode LOAD_FAST ottimizzati che operano su un array di dimensioni fisse piuttosto che eseguire ricerche in tabelle hash più lente. Questa ottimizzazione è fondamentale per le prestazioni delle chiamate di funzione di Python, ma introduce requisiti di binding rigorosi.
Quando un nome è classificato come locale, il compilatore emette istruzioni bytecode LOAD_FAST per tutte le operazioni di lettura di quel nome. Durante il runtime, LOAD_FAST tenta di recuperare il riferimento all'oggetto dall'indice corrispondente nell'array delle variabili locali del frame. Se lo slot contiene un puntatore nullo che indica che non è stato ancora assegnato alcun valore, il runtime solleva un UnboundLocalError. Questo accade anche se esiste una variabile globale con lo stesso nome, perché il compilatore ha deliberatamente evitato di emettere LOAD_GLOBAL. L'errore indica esplicitamente questa decisione di scoping statico, distinguendola da NameError.
Per risolvere questo, devi informare esplicitamente il compilatore che il nome si riferisce allo spazio dei nomi globale dichiarando global <nome_variabile>. Questa dichiarazione induce il compilatore a passare a LOAD_GLOBAL e STORE_GLOBAL, che cercano dinamicamente il nome nel dizionario globale del modulo. In alternativa, puoi ristrutturare il codice per garantire che tutte le variabili locali siano inizializzate all'inizio della funzione prima che qualsiasi logica condizionale le legga. Per scopi annidati, la parola chiave nonlocal costringe il compilatore ad utilizzare LOAD_DEREF per accedere alle celle di chiusura. Queste dichiarazioni modificano la decisione di binding del compilatore durante il tempo di compilazione, prevenendo lo scenario della variabile locale non vincolata.
threshold = 100 def analyze(data): # Il compilatore vede 'threshold = ...' di seguito, lo segna come locale if data > threshold: # Solleva UnboundLocalError return "high" threshold = 50 # L'assegnazione lo rende locale # Soluzione usando 'global' def analyze_fixed(data): global threshold if data > threshold: # LOAD_GLOBAL ha successo return "high" threshold = 50 # Aggiorna la variabile globale
Un team di ingegneria dei dati stava costruendo una pipeline ETL usando Apache Airflow. Hanno definito un dizionario di configurazione predefinito CONFIG = {"batch_size": 1000} a livello di modulo per consentire un facile aggiustamento dei parametri di elaborazione. La funzione di trasformazione principale process_batch() inizialmente controllava if len(records) > CONFIG["batch_size"]: per determinare se era necessario suddividere i dati. Poi, in una condizione specifica all'interno della funzione, il codice ha tentato di ottimizzare la memoria riducendo la dimensione del batch con CONFIG = {"batch_size": 500}. Questo schema ha inavvertitamente attivato un conflitto di scoping.
Quando la pipeline è stata eseguita, è andata in crash sulla prima riga della funzione con UnboundLocalError: variabile locale 'CONFIG' riferita prima dell'assegnazione. L'istruzione di assegnazione alla fine della funzione ha indotto il compilatore Python a trattare CONFIG come una variabile locale per l'intero corpo della funzione. Di conseguenza, l'operazione di confronto all'inizio ha utilizzato LOAD_FAST per accedere allo slot della variabile locale non inizializzato. Questo fallimento ha bloccato la pipeline dei dati durante un'importante esecuzione in produzione perché la funzione non è riuscita a iniziare l'esecuzione.
Il team ha prima considerato di rinominare la riassegnazione locale in local_config, creando un nuovo dizionario per l'elaborazione del batch ridotto. Questo avrebbe evitato completamente il problema di ombreggiamento e mantenuto immutabile la configurazione globale. Tuttavia, questo approccio richiedeva la rifattorizzazione del codice a valle che si aspettava che il nome CONFIG riflettesse i limiti attuali. Ha introdotto potenziali inconsistenze se lo sviluppatore si fosse dimenticato di usare il nuovo nome della variabile nella logica successiva. Il sovraccarico cognitivo di tracciare due nomi di variabile per lo stesso concetto ha reso questa soluzione meno attraente.
Un'altra opzione era aggiungere global CONFIG all'inizio della funzione, costringendo il compilatore a trattare tutti i riferimenti come ricerche globali. Sebbene questo avrebbe evitato l'errore, il team lo ha rifiutato in quanto modificare lo stato globale durante un processo batch è un pericoloso anti-pattern. Impedisce la reentranza della funzione e complica significativamente i test unitari. Inoltre, creerebbe condizioni di gara se il codice fosse mai parallelizzato su thread. Gli effetti collaterali sullo stato a livello di modulo sono stati considerati inaccettabili per le pipeline di dati in produzione.
La terza soluzione prevedeva di mutare il dizionario esistente in loco usando CONFIG["batch_size"] = 500 piuttosto che riassegnare il nome della variabile stessa. Poiché questa operazione non crea un nuovo binding per il nome CONFIG, il compilatore continua a trattarlo come un riferimento globale. Questo evita UnboundLocalError consentendo nel contempo che l'aggiornamento della configurazione persista per le chiamate successive. Questa è stata ritenuta la migliore soluzione immediata, anche se il team ha pianificato di rifattorizzare la configurazione in un'istanza di classe in seguito. L'approccio della mutazione ha preservato l'API esistente risolvendo contemporaneamente il crash immediato.
Hanno implementato la terza soluzione, cambiando la riassegnazione in una mutazione CONFIG["batch_size"] = 500. La pipeline ha ripreso l'esecuzione senza errori e la modifica della configurazione è stata applicata correttamente ai batch successivi. In seguito, hanno rifattorizzato il codice per utilizzare un oggetto di impostazioni Pydantic iniettato nella funzione. Questo ha completamente rimosso la dipendenza dalle variabili globali a livello di modulo e ha reso la funzione pura e testabile. L'incidente ha portato a una revisione del codice di tutti gli operatori Airflow per eliminare schemi di ombreggiamento simili.
Perché eliminare una variabile all'interno di una funzione, seguito da un tentativo di leggerla, solleva UnboundLocalError invece di tornare allo scopo globale?
Quando esegui del x su una variabile locale, rimuove il riferimento dal f_locals del frame ma non modifica la classificazione statica di x come locale. Il compilatore ha comunque generato LOAD_FAST per le letture successive. Quando l'interprete esegue LOAD_FAST, trova lo slot vuoto e solleva UnboundLocalError piuttosto che tornare ai globali. Questo conferma che le decisioni di scoping sono immutabili durante il runtime. Per accedere a un globale x dopo la cancellazione, devi dichiarare global x durante il tempo di compilazione.
Come evitano le espressioni di argomenti predefiniti la trappola di UnboundLocalError, e cosa rivela questo sul loro tempo di valutazione?
Gli argomenti predefiniti vengono valutati una sola volta quando la definizione della funzione viene eseguita nello scopo circostante, non all'interno dello scopo locale della funzione. Se scrivi def f(val=CONFIG["key"]):, Python utilizza LOAD_GLOBAL per risolvere CONFIG al momento della definizione. Anche se il corpo della funzione successivamente assegna a CONFIG, rendendolo locale, il predefinito è già stato catturato in modo sicuro. Questo rivela che i valori predefiniti utilizzano lo scopo globale al momento della definizione, separato dall'esecuzione locale del corpo della funzione. Pertanto, i predefiniti evitano l'UnboundLocalError che si verificherebbe se l'accesso fosse avvenuto all'interno del corpo della funzione prima dell'assegnazione.
Perché UnboundLocalError non si verifica mai nei corpi delle classi, e quale differenza di bytecode lo consente?
I corpi delle classi utilizzano LOAD_NAME invece di LOAD_FAST per l'accesso alle variabili. LOAD_NAME esegue una ricerca dinamica nel dizionario della classe, quindi nel dizionario globale, quindi in builtins. Non utilizza uno slot pre-allocato di dimensioni fisse, quindi non incontra mai uno stato "locale non vincolato". Se un nome viene fatto riferimento prima dell'assegnazione in un corpo di classe, LOAD_NAME procede semplicemente a trovarlo nello scopo globale. Questo approccio basato su dizionario scambia la velocità delle variabili locali della funzione per la flessibilità necessaria durante la costruzione della classe.