3.3.1 Personalizzazioni di base

__init__( self[, ...])
Chiamata quando viene creata un'istanza. Gli argomenti vengono passati al costruttore della classe. Se una classe base ha un metodo __init__(), il metodo __init__() della classe derivata, se esiste, deve esplicitamente richiamarlo per assicurare l'appropriata inizializzazione relativa alla classe base dell'istanza; per esempio: "BaseClass.__init__(self, [args...])". Come una speciale costrizione sui costruttori, non può essere restituito alcun valore; facendolo verrà sollevata un'eccezione TypeError al runtime.

__del__( self)
Chiamata quando l'istanza può essere distrutta. Viene anche chiamata distruttore. Se una classe base ha un metodo __del__(), il metodo __del__() della classe derivata, se esiste, deve esplicitamente richiamarlo per assicurare l'appropriata distruzione relativa alla classe di base dell'istanza. Si noti che è possibile (benché non raccomandato) posporre la distruzione dell'istanza da parte del metodo __del__() creando un nuovo riferimento all'istanza. Questa può quindi essere chiamata in un secondo tempo quando questo nuovo riferimento viene cancellato. Non viene garantito che i metodi __del__() vengano chiamati per gli oggetti che esistono quando si esce dall'interprete.

Note: "del x" non chiama direttamente x.__del__() -- il primo decrementa il contatore di riferimenti per x di uno, mentre l'altro viene chiamato solo quando il contatore di riferimenti per x raggiunge zero. Alcune situazioni comuni che possono prevenire il raggiungimento di zero da parte del contatore di riferimenti di un oggetto include: riferimenti circolari tra oggetti (per esempio, una lista doppiamente linkata o una struttura dati ad albero con parenti e figli puntatori); un riferimento all'oggetto nel frame dello stack di una funzione che può sollevare un'eccezione (il traceback memorizzato in sys.exc_traceback mantiene il frame dello stack attivo); o un riferimento all'oggetto che nel frame dello stack raggiunge un eccezione non gestita in modo interattivo (il traceback memorizzato in sys.last_traceback mantiene il frame dello stack attivo). La prima situazione può essere rimediata solo da un'esplicita rottura dei cicli; le ultime due situazioni possono essere risolte memorizzando None in sys.exc_traceback o sys.last_traceback. Riferimenti circolari inutili vengono scoperti quando viene abilitata l'opzione cycle detector (è attiva in modo predefinito), ma possono essere ripuliti solo se non ci sono metodi __del__() coinvolti a livello Python. Far riferimento alla documentazione del modulo gc per maggiori informazioni su come i metodi __del__() vengono gestiti dai cycle detector, in particolare la descrizione del valore della garbage.

A causa delle precarie circostanze sotto le quali i metodi __del__() vengono invocati, le eccezioni sollevate durante la loro esecuzione vengono ignorate, al loro posto viene stampato un avviso su sys.stderr. Inoltre, quando __del__() viene invocato come risposta ad un modulo che deve essere rimosso (per esempio, quando l'esecuzione di un programma raggiunge il termine), altri riferimenti globali referenziati dal metodo __del__() possono dover essere cancellati. Per questa ragione, i metodi __del__() dovrebbero fare il minimo indispensabile in assoluto per mantenere l'esterno invariato. Dalla versione 1.5, Python garantisce che questi riferimenti globali i cui nomi iniziano con un singolo carattere di sottolineatura siano rimossi dai propri moduli prima che altri riferimenti globali vengano rimossi; il fatto che non esistano altri riferimenti globali assicura che i moduli importati siano ancora disponibili al momento della chiamata al metodo __del__().

__repr__( self)
Chiamata dalla funzione built-in repr() e da conversioni in stringa (virgolette rovesciate) per calcolare la rappresentazione ``ufficiale'' di un oggetto stringa. Se tutto è possibile, questa dovrebbe essere vista come una valida espressione Python che potrebbe essere usata per ricreare un oggetto con lo stesso valore (stabilendo un ambiente appropriato). Se questo non è possibile, dovrebbe essere restituita una stringa nella forma "<...qualche utile descrizione...>". Il valore restituito deve essere un oggetto stringa. Se una classe definisce __repr__() ma non __str__(), il metodo __repr__() verrà usato anche quando verrà richiesta una rappresentazione di stringa ``informale'' di istanze richieste da questa classe.

Questo è il tipico uso per il debugging, pertanto è importante che la rappresentazione sia ricca di informazioni e non ambigua.

__str__( self)
Chiamato dalla funzione built-in str() e dall'istruzione print per calcolare la rappresentazione di stringa ``informale'' di un oggetto, che differisce da __repr__() in quanto non deve essere un'espressione valida Python: può, invece, venire usata una rappresentazione più adatta e concisa. Il valore restituito deve essere un oggetto stringa.

__lt__( self, other)
__le__( self, other)
__eq__( self, other)
__ne__( self, other)
__gt__( self, other)
__ge__( self, other)
Nuovo nella versione 2.1. Questi sono i cosiddetti metodi di ``confronto ricco'' e vengono usati per confrontare degli operatori con priorità a __cmp__() preso in esame di seguito. La corrispondenza tra operatori e metodi è la seguente: x<y chiama x.__lt__(y), x<=y chiama x.__le__(y), x==y chiama x.__eq__(y), x!=y e x<>y chiama x.__ne__(y), x>y chiama x.__gt__(y) e x>=y chiama x.__ge__(y). Questi metodi possono restituire qualsiasi valore, ma se l'operatore di confronto viene usato in un contesto booleano, il valore restituito dovrebbe essere interpretabile come un valore booleano, altrimenti viene sollevata un'eccezione TypeError. Per convenzione, False viene usato per falso e True per vero.

Non ci sono relazioni implicite tra gli operatori di confronto. Il fatto che x==y sia vero non implica che x!=y sia falso. Per questo, definendo __eq__, si dovrebbe anche definire __ne__ in modo che gli operatori si comportino come ci si aspetta.

Non ci sono versioni riflesse (con argomenti scambiati) di questi metodi (quando cioè l'argomento di sinistra non supporta l'operazione mentre lo supporta l'argomento di destra); piuttosto, __lt__() e __gt__() sono l'una il contrario dell'altra, la stessa cosa per __le__() e __ge__() ed anche __eq__() e __ne__() riflettono la medesima situazione.

Gli argomenti dei metodi di confronto ricco non vengono mai forzati. Un metodo di confronto può restituire NotImplemented se l'operazione tra la coppia di argomenti non viene implementata.

__cmp__( self, other)
Chiamato da operazioni di confronto se un metodo di confronto (si veda sopra) non è stato definito. Dovrebbe restituire un intero negativo se self < other, zero se self == other, un intero positivo se self > other. Se non viene definita alcuna operazione __cmp__(), __eq__() o __ne__(), istanze di classe vengono confrontate tramite oggetti identità (``indirizzi''). Si veda anche la descrizione di __hash__() per alcune note sulla creazione di oggetti che supportino operazioni di confronto personalizzate e che siano utilizzabili come chiavi di dizionari. (Nota: la restrizione che le eccezioni non vengano propagate da __cmp__() è stata rimossa a partire dalla versione 1.5 di Python.)

__rcmp__( self, other)
Modificato nella versione 2.1: Non più supportato.

__hash__( self)
Chiamato per oggetti chiave in operazioni su dizionari e dalla funzione built-in hash(). Dovrebbe restituire un intero a 32-bit utilizzabile come un valore di hash per operazioni su dizionari. L'unica proprietà richiesta è che oggetti uguali abbiano lo stesso valore di hash; viene consigliato di mischiare insieme, in qualche modo (per esempio usando un'or esclusivo), i valori di hash per i componenti dell'oggetto che gioca anche un ruolo nel confronto di oggetti. Se in una classe non viene definito un metodo __cmp__() non dovrebbe venire definita neanche un'operazione __hash__(); se viene definito __cmp__() o __eq__() ma non __hash__(), la sua istanza non potrà essere usata come chiave di un dizionario. Se in una classe vengono definiti oggetti mutabili e viene implementato un metodo __cmp__() o __eq__(), non si dovrebbe implementare __hash__() dato che l'implementazione di un dizionario richiede che un valore hash di una chiave sia immutabile (se il valore hash dell'oggetto cambia, si otterrà un hash errato).

__nonzero__( self)
Chiamato per implementare un test su un valore vero o dall'operazione built-in bool(); dovrebbe restituire False o True, o il loro equivalente numerico (0 o 1). Quando questo metodo non viene definito, viene richiamato __len__() se definito (si veda di seguito). Se in una classe non vengono definiti né __len__()__nonzero__(), tutte le loro istanze vengono considerate vere.

__unicode__( self)
Chiamato per implementare la funzione built-in functionunicode(); dovrebbe restituire un oggetto Unicode. Quando questo metodo non viene definito, viene tentata la conversione in stringa ed il risultato della conversione in stringa viene convertito in Unicode usando il sistema di codifica predefinito.

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