3.3.5 Emulare i tipi contenitore

I metodi seguenti possono essere definiti per implementare gli oggetti contenitore. I contenitori sono solitamente sequenze (come le liste o le tuple) o mappe (come i dizionari), ma possono rappresentare altri contenitori altrettanto bene. Il primo insieme di metodi viene usato sia per emulare una sequenza che per emulare una mappa; la differenza è che per una sequenza, le chiavi ammissibili dovrebbero essere numeri interi k in cui 0 <= k < N dove N è la lunghezza della sequenza, od oggetti fetta, che definiscono una gamma di articoli. (Per compatibilità all'indietro, il metodo __getslice__() (si veda più avanti) può essere definito anche per maneggiare fette semplici, ma non estese.) Si raccomanda inoltre che quelle mappe forniscano i metodi keys(), values(), items(), has_key(), get(), clear(), setdefault(), iterkeys(), itervalues(), iteritems(), pop(), popitem(), copy() e update(), con un comportamento simile a quello per gli oggetti dizionari standard di Python. Il modulo UserDict fornisce una classe DictMixin per aiutare la creazione di quei metodi da un insieme base di __getitem__(), __setitem__(), __delitem__() e keys(). Le sequenze mutabili dovrebbero fornire i metodi append(), count(), index(), extend(), insert(), pop(), remove(), reverse() e sort(), come gli oggetti lista standard di Python. Infine, i tipi di sequenze dovrebbero implementare l'addizione (intendendo la concatenazione) e la moltiplicazione (intendendo la ripetizione) definendo i metodi __add__(), __radd__(), __iadd__(), __mul__(), __rmul__() e __imul__() descritti sotto; essi non dovrebbero definire __coerce__() o altri operatori numerici. Si raccomanda che sia le mappe che le sequenze implementino il metodo __contains__() per consentire un uso efficiente dell'operatore in; per le mappe, in dovrebbe essere equivalente adhas_key(); per le sequenze, esso dovrebbe cercare attraverso i valori. Si raccomanda inoltre che sia le mappe che le sequenze implementino il metodo __iter__() per consentire un'iterazione efficiente attraverso il contenitore; per le mappe, __iter__() dovrebbe essere lo stesso di iterkeys(); per le sequenze, dovrebbe iterare attraverso i valori.

__len__( self): Chiamato per implementare la funzione built-in len(). Dovrebbe restituire la lunghezza dell'oggetto, un numero intero >= 0. Inoltre, un oggetto che non definisce un metodo __nonzero__() e del cui metodo __len__() restituisce zero viene considerato come falso in un contesto booleano.

__getitem__( self, key): Chiamato ad implementare una valutazione di self[key]. Per i tipi sequenza, le chiavi accettate dovrebbero essere numeri interi ed oggetti fetta. Si noti che l'interpretazione speciale degli indici negativi (se la classe desidera emulare un tipo sequenza) spetta al metodo __getitem__(). Se la chiave key è di un tipo inappropriato, potrebbe essere sollevata l'eccezione TypeError; se un valore risulta al di fuori dell'insieme di indici per la sequenza (dopo qualsiasi interpretazione speciale dei valori negativi), potrebbe essere sollevata l'eccezione IndexError. Note: Per i cicli for ci si aspetta che venga sollevata un'eccezione IndexError per indici illegali, in modo da consentire una corretta rilevazione della fine della sequenza.

__setitem__( self, key, value): Chiamato ad implementare assegnamenti a self[key]. Stessa nota per __getitem__(). Questo dovrebbe essere implementato solo per le mappe se l'oggetto supporta cambi ai valori per chiavi, o se nuove chiavi possono essere aggiunte, o per sequenze se gli elementi possono essere sostituiti. Le stesse eccezioni dovrebbero essere sollevate per valori chiave key impropri per quanto riguarda il metodo __getitem__().

__delitem__( self, key): Chiamato ad implementare l'eliminazione di self[key]. Stessa nota per __getitem__(). Questo dovrebbe essere implementato solo per le mappe se gli oggetti supportano la rimozione delle chiavi, o per le sequenze se gli elementi possono essere rimossi dalla sequenza. Le stesse eccezioni dovrebbero essere sollevate per valori chiave, key, impropri per quanto riguarda il metodo __getitem__().

__iter__( self): Questo metodo viene chiamato quando un iteratore viene richiesto per un contenitore. Questo metodo dovrebbe restituire un nuovo oggetto iteratore che può iterare su tutti gli oggetti nel contenitore. Per le mappe, dovrebbe iterare sopra le chiavi del contenitore, e dovrebbe anche essere reso disponibile come il metodo iterkeys().
Gli oggetti iteratori devono necessariamente implementare anche questo metodo; vengono richiesti per restituire loro stessi. Per maggiori informazioni sugli oggetti iteratore, si veda ``Tipi iteratori'' nella Libreria di riferimento di Python.

Gli operatori per le verifiche di appartenenza (in e not in) vengono usualmente implementati come un'iterazione per mezzo di una sequenza. Tuttavia, gli oggetti contenitore possono fornire i seguenti metodi speciali di un'implementazione di maggiore efficienza, che inoltre non richiede che l'oggetto sia una sequenza.

__contains__( self, item): Chiamato per implementare operatori che verifichino l'appartenenza. Dovrebbe restituire vero se l'elemento item è all'interno di self, altrimenti falso. Per gli oggetti mappa, questo dovrebbe considerare le chiavi della mappa piuttosto che i valori o le coppie elementi-chiave.

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