3.3 `weakref` -- Riferimenti deboli

Nuovo nella versione 2.1.

Il modulo weakref permette al programmatore Python di creare riferimenti deboli agli oggetti.

Di seguito, il termine referente indica l'oggetto a cui ci si riferisce con un riferimento debole.

Un riferimento debole a un oggetto non è sufficiente per tenere un oggetto in vita: quando l'unico riferimento restante a un referente è un riferimento debole, la garbage collection è libera di distruggere il referente e riusare la sua memoria per qualche altra cosa. Il principale uso di un riferimento debole è quello di implementare cache o assegnamenti contenenti grandi oggetti, dove è preferibile che un grande oggetto non debba essere tenuto vivo per il solo fatto che appare in una cache o in un assegnamento. Per esempio, se si ha un gran numero di immagini binarie di oggetti, si potrebbe desiderare di associare un nome a ciascuna di esse. Se si utilizza un dizionario Python per assegnare nomi a immagini, o immagini a nomi, gli oggetti immagine potrebbero restare in vita solo perché appaiono come valori o chiavi all'interno dei dizionari. Le classi WeakKeyDictionary e WeakValueDictionary fornite attraverso il modulo weakref rappresentano un'alternativa, usando riferimenti deboli per costruire assegnamenti che non mantengono vivi gli oggetti solo perché essi appaiono in un assegnamento di oggetti. Se, per esempio, un oggetto immagine è un valore in un WeakValueDictionary, quando gli ultimi riferimenti a quell'oggetto immagine sono dei riferimenti deboli mantenuti da assegnamenti deboli, la garbage collection può richiedere l'oggetto, e la sua corrispondente registrazione nella mappa dei riferimenti deboli viene semplicemente cancellata.

WeakKeyDictionary e WeakValueDictionary usano riferimenti deboli nella loro implementazione, impostando una chiamata di ritorno di funzioni sui riferimenti deboli che notificano ai dizionari deboli quando una chiave o un valore viene richiesto dalla garbage collection. Molti programmatori potrebbero verificare che l'uso di uno di questi tipi di dizionari deboli è tutto ciò di cui necessitano - di regola non è necessario creare i propri riferimenti deboli direttamente. L'implementazione di basso livello usata dal dizionario debole viene mostrata dal modulo weakref per beneficiarne negli usi più avanzati.

Non tutti gli oggetti possono venire riferiti debolmente; gli oggetti che godono di questa proprietà sono istanze di classe, funzioni scritte in Python (ma non in C), e metodi (sia diretti che indiretti). Tipi di estensione possono venire facilmente creati per supportare i riferimenti deboli; per ulteriori informazioni vedete la sezione 3.3.3 ``Riferimenti deboli nei tipi di estensione''.

ref( oggetto[, callback])

Restituisce un riferimento debole ad un oggetto. L'oggetto originale può venire recuperato chiamando l'oggetto di riferimento se il referente è ancora vivo; se invece non lo è più, chiamare il riferimento all'oggetto comporterà la restituzione di None. Se viene fornita una callback, questa verrà usata quando l'oggetto sarà prossimo alla finalizzazione; l'oggetto con riferimenti deboli verrà passato come parametro alla chiamata di ritorno; il referente non sarà più disponibile.

È consentito che riferimenti deboli multipli vengano costruiti intorno allo stesso oggetto. Le chiamate di ritorno registrate per ogni riferimento debole verranno sfruttate in ordine cronologico dalla più recente (cioè da quella registrata per ultima) alla più vecchia (quella registrata per prima).

Le eccezioni sollevate dalla chiamata di ritorno verranno indicate sullo standard error, ma non possono essere propagate; vengono gestite esattamente nella stessa maniera delle eccezioni generate dal metodo __del__() di un oggetto.

I riferimenti deboli sono hashabili se l'oggetto è hashabile. Manterranno il loro valore di hash anche dopo che l'oggetto è stato rimosso. Se la funzione hash() viene chiamata per la prima volta solo dopo che l'oggetto è stato rimosso, la chiamata solleverà un'eccezione TypeError.

I riferimenti deboli supportano i test di uguaglianza, ma non di ordinamento. Se i referenti sono ancora in vita, due riferimenti hanno la stessa relazione di uguaglianza che esiste tra gli oggetti referenti (indipendentemente dalle funzioni di callback). Se entrambi entrambi i referenti vengono cancellati, i riferimenti sono uguali solo se gli oggetti referenti sono lo stesso oggetto.

proxy( oggetto[, callback]): Restituisce un proxy ad un oggetto che usa un riferimento debole. Questo supporta l'uso del proxy nella maggior parte dei contesti, invece di richiedere una esplicita dereferenziazione usata con oggetti che hanno riferimenti deboli. L'oggetto restituito erediterà il tipo di uno dei due, ProxyType oppure CallableProxyType, a seconda di quale oggetto sia chiamabile. Gli oggetti proxy non sono hashabili, indipendentemente dal referente; questo evita una serie di problemi legati alla loro natura fondamentalmente mutabile, e previene il loro utilizzo come chiavi dei dizionari. La chiamata di ritorno è la stessa come il parametro con lo stesso nome dato alla funzione ref().

getweakrefcount( oggetto): Restituisce il numero di riferimenti deboli e i proxy che si riferiscono all'oggetto.

getweakrefs( oggetto): Restituisce una lista di tutti i riferimenti deboli e oggetti proxy che si riferiscono all'oggetto.

class WeakKeyDictionary( [dict]): È una classe di mappatura che riferisce debolmente le chiavi. Le voci nel dizionario verranno scartate quando non c'è più un riferimento forte alla chiave. Questo classe può venire usata per associare dati aggiuntivi ad un oggetto che appartiene ad altre parti di un'applicazione, senza aggiungere attributi a questi oggetti. Può essere di particolare utilità con oggetti che sovrascrivono gli attributi degli accessi.
Note: Avvertenza: Dal momento che un WeakKeyDictionary viene costruito sopra un dizionario Python, non deve cambiare dimensione quando vengono eseguite delle iterazioni su di esso. Questo può essere difficile da garantire per un WeakKeyDictionary perché le azioni eseguite dal programma durante l'iterazione possono portare alcuni elementi a svanire ``per magia'' (come effetto collaterale della garbage collection).

class WeakValueDictionary( [dict]): Classe di mappatura che riferisce valori debolmente. Le voci nel dizionario verranno scartate quando non esiste più un riferimento forte al valore.
Note: Avvertenza: Dal momento che un WeakValueDictionary viene costruito sopra un dizionario Python, non deve cambiare dimensione quando vengono eseguite delle iterazioni su di esso. Questo può essere difficile da garantire per un WeakValueDictionary perché le azioni eseguite dal programma durante l'iterazione possono portare alcuni elementi a svanire ``per magia'' (come effetto collaterale della garbage collection).

ReferenceType: Il tipo di oggetto per oggetti con riferimenti deboli.

ProxyType: Il tipo di oggetto per proxy di oggetti che non sono chiamabili.

CallableProxyType: Il tipo di oggetto per proxy di oggetti chiamabili.

ProxyTypes: Sequenza contenente tutti i tipi di oggetti per i proxy. Questa può rendere più semplice verificare se un oggetto è un proxy senza dover nominare entrambi i tipi di proxy.

exception ReferenceError: Eccezione sollevata quando un oggetto proxy viene utilizzato ma l'oggetto sottostante è stato inserito nella garbage collection. Equivale all'eccezione standard ReferenceError.

Vedete anche:

PEP 0205, Weak References: La proposta ed il fondamento logico per questa caratteristica, comprendente i link a precedenti implementazioni e le informazioni riguardanti funzioni simili in altri linguaggi.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.

3.3 weakref -- Riferimenti deboli

3.3 `weakref` -- Riferimenti deboli