2.4 Eccezioni built-in

Le eccezioni dovrebbero essere classi oggetto. Le eccezioni vengono definite nel modulo exceptions. Questo modulo non ha mai bisogno di essere importato esplicitamente: le eccezioni vengono fornite nello spazio dei nomi built-in, alla stessa maniera del modulo exceptions.

Note: Nelle versioni passate di Python le eccezioni stringa venivano supportate. In Python 1.5 e nelle versioni più recenti, tutte le eccezioni standard sono state convertite in classi oggetto e gli utenti vengono incoraggiati a fare altrettanto. Le eccezioni stringa solleveranno un'eccezione PendingDeprecationWarning. In versioni future, verrà rimosso il supporto per le eccezioni delle stringhe.

Due differenti oggetti stringa con lo stesso valore vengono considerati due eccezioni differenti. Questo è stato fatto per forzare i programmatori ad usare il nome delle eccezioni invece del loro valore stringa, quando specificano i gestori delle eccezioni. Il valore stringa di tutte le eccezioni built-in è il loro nome, ma questo non è un requisito per le eccezioni definite dall'utente o dalle eccezioni definite dai moduli della libreria.

Per le classi delle eccezioni, in una istruzione try con una clausola except che menziona una classe particolare, quella clausola gestisce anche ogni classe di eccezione derivata da quella classe (ma non la classe eccezione dalla quale è derivata). Due classi di eccezioni non relazionate attraverso una classe derivata non saranno mai equivalenti, anche se hanno lo stesso nome.

Le eccezioni built-in elencate qui sotto possono essere generate dall'interprete o dalle funzioni built-in. Fatta eccezione dove indicato, hanno un ``valore associato'' indicante la causa dettagliata dell'errore. Questo può essere una stringa o una tupla contenente vari elementi informativi (p.es., un errore nel codice ed una stringa che spiega il codice). Il valore associato è il secondo argomento per l'istruzione raise. Per le eccezioni delle stringhe, il valore associato stesso verrà raccolto in una variabile chiamata come il secondo argomento della clausola except (se esiste). Per le classi eccezione, quella variabile riceve l'istanza dell'eccezione. Se la classe eccezione deriva dalla classe standard originaria Exception, il valore associato è presente come istanza di eccezione dell'attributo args, e possibilmente anche su altri attributi.

Il codice dell'utente può sollevare un'eccezione built-in. Questo può venire usato per testare un generatore di eccezioni o per riportare una condizione di errore ``appositamente pensata'' per la situazione nella quale l'interprete solleva l'eccezione stessa; ma fate attenzione, che non esiste nulla per evitare un errore improprio prodotto nel codice utente.

Le classi delle eccezioni built-in possono essere sotto classi, create per definire nuove eccezioni; i programmatori sono incoraggiati a derivare almeno le nuove eccezioni dalla classe base Exception. Ulteriori informazioni sulla definizione delle eccezioni sono disponibili nel Tutorial Python sotto la voce ``Eccezioni definite dall'utente''.

Le seguenti eccezioni vengono usate soltanto come classi di base per altre eccezioni.

exception Exception: La classe originaria per le eccezioni. Tutte le eccezioni built-in derivano da questa classe. Anche tutte le eccezioni definite dall'utente dovrebbero derivare da questa classe, ma questo non viene (ancora) imposto. La funzione str(), quando applicata ad un'istanza di questa classe (o a più classi derivate), restituisce il valore stringa dell'argomento o degli argomenti, oppure una stringa vuota se nessun argomento è stato passato al costruttore. Quando usata come una sequenza, questa accede agli argomenti dati al costruttore (per retrocompatibilità con il vecchio codice). Gli argomenti sono anche disponibili come una tupla delle istanze dell'attributo args.

exception StandardError: La classe base per tutte le eccezioni built-in eccetto StopIteration e SystemExit. StandardError stessa è derivata dalla classe originaria Exception.

exception ArithmeticError: La classe base per quelle eccezioni built-in che vengono sollevate per vari errori aritmetici: OverflowError, ZeroDivisionError, FloatingPointError.

exception LookupError: La classe base per le eccezioni che vengono sollevate quando una chiave o un indice usato in una mappa o in una sequenza non è valida: IndexError, KeyError. Questa può essere sollevata direttamente da sys.setdefaultencoding().

exception EnvironmentError

La classe base per le eccezioni che possono verificarsi al di fuori del sistema Python: IOError, OSError. Quando eccezioni di questo tipo vengono create con una 2-tuple, il primo elemento è disponibile nell'istanza dell'attributo errno (si presuppone essere un errore numerico), ed il secondo elemento è disponibile sull'attributo strerror (solitamente è il messaggio di errore associato). La tupla stessa è anche disponibile nell'attributo args. Nuovo nella versione 1.5.2.

Quando una eccezione di tipo EnvironmentError viene istanziata con una 3-tuple, i primi due elementi sono disponibili come sopra, mentre il terzo elemento è disponibile nell'attributo filename. Tuttavia, per retrocompatibilità, l'attributo args contiene solo 2-tuple dei primi due argomenti del costruttore.

L'attributo filename è None quando questa eccezione viene creata con un numero di argomenti diverso da 3. Gli attributi errno e strerror sono anche None quando l'istanza viene creata con un numero di argomenti diverso da 2 o 3. In quest'ultimo caso, args contiene letteralmente il costruttore di argomenti sotto forma di tupla.

Le seguenti eccezioni sono quelle che vengono attualmente sollevate.

exception AssertionError: Viene sollevata quando un'istruzione assert fallisce.

exception AttributeError: Viene sollevata quando un riferimento ad un attributo o ad un assegnamento fallisce. (Nel caso in cui un oggetto non supporti affatto i riferimenti ad un attributo o gli assegnamenti ad un attributo, viene sollevata un'eccezione di tipo TypeError).

exception EOFError: Viene sollevata quando una delle funzioni built-in (input() o raw_input()) incontra un codice di controllo indicante la la fine del file (EOF) senza avere letto alcun dato. (N.B.: I metodi read() e readline() del file oggetto restituiscono una stringa vuota quando incontrano un EOF.)

exception FloatingPointError: Viene sollevata quando un'operazione in virgola mobile fallisce. Questa eccezione è sempre definita, ma può venire sollevata quando Python viene configurato con l'opzione --with-fpectl, oppure quando il simbolo WANT_SIGFPE_HANDLER viene definito nel file pyconfig.h.

exception IOError: Viene sollevata quando una operazione di I/O (come un'istruzione print, la funzione built-in open() o il metodo di un file oggetto) fallisce per una ragione legata all'I/O, p.es. ``file not found'' o ``disk full''.
Questa classe deriva da EnvironmentError. Vedete la discussione relativa per maggiori informazioni sugli attributi delle istanze di eccezione.

exception ImportError: Viene sollevata quando un'istruzione import fallisce nella ricerca della definizione del modulo, o quando l'importazione in un ciclo from ... import fallisce la ricerca del nome che deve essere importato.

exception IndexError: Viene sollevata quando una sequenza in un sottoscript è fuori dall'intervallo. (Gli indici delle fette vengono troncati silenziosamente per rientrare nell'intervallo consentito; un'eccezione di tipo TypeError viene sollevata se un indice non è un intero semplice).

exception KeyError: Viene sollevata quando una chiave di mappa (dizionario) non viene trovata nell'insieme delle chiavi esistenti.

exception KeyboardInterrupt: Viene sollevata quando l'utente preme la combinazione interrupt (normalmente Control-C or Delete). Durante l'esecuzione, un controllo per gli interrupt viene fatto regolarmente. Gli interrupt digitati quando una funzione built-in input() o raw_input() è in attesa di input, sollevano ugualmente questa eccezione.

exception MemoryError: Viene sollevata quando una operazione esegue un out of memory ma la situazione può essere ancora recuperata (cancellando alcuni oggetti). Il valore associato è una stringa indicante quale tipo di operazione (interna) è stata eseguita out of memory. Notate che in questa situazione, a causa dell' architettura di gestione della memoria sottostante (la funzione C malloc()), l'interprete non sempre riesce ad effettuare un completo recupero; tuttavia solleva un'eccezione, in modo da poter stampare una traccia dello stack, nel caso in cui sia stata provocata da un programma in esecuzione.

exception NameError: Viene sollevata quando un nome locale o globale non viene trovato. Questo si applica solo ai nomi non qualificati. Il valore associato è un messaggio di errore che include il nome che non può essere trovato.

exception NotImplementedError: Questa eccezione viene derivata da RuntimeError. Nelle classi base definite dall'utente, i metodi astratti dovrebbero sollevare questa eccezione quando richiedono delle classi derivate per sovrascrivere il metodo. Nuovo nella versione 1.5.2.

exception OSError: Questa classe viene derivata dal EnvironmentError e viene usata principalmente come l'eccezione os.error del modulo os. Vedete EnvironmentError, in precedenza, per la descrizione dei possibili valori associati. Nuovo nella versione 1.5.2.

exception OverflowError: Viene sollevata quando il risultato di un'operazione aritmetica è troppo grande per essere rappresentato. Questo non può accadere per gli interi long (che dovrebbero semmai sollevare un'eccezione MemoryError piuttosto che desistere dall'operazione). A causa della mancanza di uno standard nel trattamento della virgola mobile in C, la maggior parte delle operazioni in virgola mobile non vengono controllate. Per gli interi semplici, tutte le operazioni che possono causare un overflow vengono controllate, tranne quelle di left shift (NdT: operazioni di scorrimento a sinistra), le cui applicazioni tipiche rendono preferibile la perdita di qualche bit piuttosto che sollevare un'eccezione.

exception ReferenceError: Questa eccezione viene sollevata quando un riferimento debole ad un proxy, creato dalla funzione weakref.proxy(), viene usato per accedere ad un attributo del referente dopo che è stato aggiunto ai dati inutili da elaborare dalla garbage collection. Per maggiori informazioni sui riferimenti deboli, vedete il modulo weakref. Nuovo nella versione 2.2: Precedentemente conosciuto come l'eccezione weakref.ReferenceError .

exception RuntimeError: Viene sollevata quando viene rilevato un errore che non ricade in nessuna delle altre categorie. Il valore associato è una stringa indicante precisamente che cosa è andato storto. (Questa eccezione è sostanzialmente una reliquia da una precedente versione dell'interprete, non viene più molto usata.)

exception StopIteration: Viene sollevata dal metodo next() di un iteratore, per segnalare che non ci sono ulteriori valori. Deriva da Exception piuttosto che da StandardError, poiché questo non viene considerato un errore neli suoi impieghi normali. Nuovo nella versione 2.2.

exception SyntaxError: Viene sollevata quando il parser incontra un errore di sintassi. Questo può verificarsi nell'istruzione import, in un'istruzione exec, in una chiamata alle funzioni built-in eval() o input(), o nella lettura dello script iniziale o dello standard input (anche interattivamente).
Istanze di questa classe hanno attributi filename, lineno, offset e text per un più facile accesso ai dettagli. L'str() dell'istanza di eccezione restituisce solo il messaggio.

exception SystemError: Viene sollevata quando l'interprete trova un errore interno, ma la situazione non sembra così seria da farci abbandonare tutte le speranze. Il valore associato è una stringa indicante che cosa è andato storto (in termini di basso livello).
Dovreste riportare questa stringa all'autore o al manutentore del vostro interprete Python. Siate sicuri di riportare la versione dell'interprete Python (sys.version; viene anche stampata all'avvio di una sessione interattiva di Python), l'esatto messaggio di errore (l'eccezione associata al valore) e se possibile il sorgente del programma che ha innescato l'errore.

exception SystemExit

Questa eccezione viene sollevata dalla funzione sys.exit(). Quando non è stata modificata, l'interprete Python esce; non viene stampata alcuna traccia. Se il valore associato è un semplice intero, specifica lo stato di uscita del sistema (passato come la funzione C exit()); se è None, lo stato di uscita è zero; se ha un altro tipo (come una stringa), il valore dell'oggetto viene stampato e lo stato di uscita è uno.

Le istanze hanno un attributo code che viene impostato per lo stato di uscita proposto o messaggio di errore (predefinito per None). Inoltre, questa eccezione deriva direttamente da Exception e non da StandardError, poiché tecnicamente non è un errore.

Una chiamata a sys.exit() viene tradotta in una eccezione in modo tale che i gestori di pulizia (le clausole finally delle istruzioni try) possano essere eseguiti, e così che il programma per il debug possa eseguire uno script senza correre il rischio di perderne il controllo. La funzione os._exit() può venire usata se è assolutamente necessario uscire immediatamente (per esempio, nel processo figlio dopo una chiamata a fork()).

exception TypeError: Viene sollevata quando un'operazione o una funzione viene applicata ad un oggetto di tipo inappropriato. Il valore associato è una stringa contenente i dettagli sul tipo errato.

exception UnboundLocalError: Viene sollevata quando viene creato un riferimento ad una variabile locale in una funzione o metodo, ma nessun valore è stato collegato a quella variabile. È una sotto classe di NameError. Nuovo nella versione 2.0.

exception UnicodeError: Viene sollevata quando interviene un errore di codifica o decodifica riferita ad Unicode. È una sotto classe di ValueError. Nuovo nella versione 2.0.

exception UnicodeEncodeError: Viene sollevata quando un errore, con riferimento ad Unicode, interviene durante la codifica. È una sotto classe di UnicodeError. Nuovo nella versione 2.3.

exception UnicodeDecodeError: Viene sollevata quando un errore, con riferimento ad Unicode, interviene durante la decodifica. È una sotto classe di UnicodeError. Nuovo nella versione 2.3.

exception UnicodeTranslateError: Viene sollevata quando un errore, con riferimento a Unicode, interviene durante la traduzione. È una sotto classe di UnicodeError. Nuovo nella versione 2.3.

exception ValueError: Viene sollevata quando un'operazione o funzione built-in ricevono un argomento che ha il tipo giusto ma valore inappropriato, e la situazione non viene descritta da una eccezione più precisa, come IndexError.

exception WindowsError: Viene sollevata quando interviene un errore specifico di Windows o quando il numero dell'errore non corrisponde ad un valore errno. I valori errno e strerror vengono creati dai valori restituiti dalle funzioni GetLastError() e FormatMessage() dell'API della piattaforma Windows. È una sotto classe di OSError. Nuovo nella versione 2.0.

exception ZeroDivisionError: Viene sollevata quando il secondo argomento di una divisione o di una operazione su di un modulo è zero. Il valore associato è una stringa indicante il tipo degli operandi e dell'operazione.

Le seguenti eccezioni vengono usate come categorie di avvertimenti; vedete il modulo warnings per maggiori informazioni.

exception Warning: Classe base della categoria degli avvertimenti.

exception UserWarning: Classe base degli avvertimenti generata dal codice utente.

exception DeprecationWarning: Classe base degli avvertimenti relativi a caratteristiche deprecate.

exception PendingDeprecationWarning: Classe base degli avvertimenti riguardanti caratteristiche che verranno deprecate in futuro.

exception SyntaxWarning: Classe base di avvertimenti riguardanti sintassi dubbie.

exception RuntimeWarning: Classe base per avvertimenti riguardanti comportamenti dubbi durante l'esecuzione.

exception FutureWarning: Classe base per avvertimenti riguardanti i costrutti che cambieranno semantica in futuro.

La gerarchia delle classi per le eccezioni built-in è:

    Exception
     +-- SystemExit
     +-- StopIteration
     +-- StandardError
     |    +-- KeyboardInterrupt
     |    +-- ImportError
     |    +-- EnvironmentError
     |    |    +-- IOError
     |    |    +-- OSError
     |    |         +-- WindowsError
     |    +-- EOFError
     |    +-- RuntimeError
     |    |    +-- NotImplementedError
     |    +-- NameError
     |    |    +-- UnboundLocalError
     |    +-- AttributeError
     |    +-- SyntaxError
     |    |    +-- IndentationError
     |    |         +-- TabError
     |    +-- TypeError
     |    +-- AssertionError
     |    +-- LookupError
     |    |    +-- IndexError
     |    |    +-- KeyError
     |    +-- ArithmeticError
     |    |    +-- OverflowError
     |    |    +-- ZeroDivisionError
     |    |    +-- FloatingPointError
     |    +-- ValueError
     |    |    +-- UnicodeError
     |    |        +-- UnicodeEncodeError
     |    |        +-- UnicodeDecodeError
     |    |        +-- UnicodeTranslateError
     |    +-- ReferenceError
     |    +-- SystemError
     |    +-- MemoryError
     +---Warning
	  +-- UserWarning
	  +-- DeprecationWarning
	  +-- PendingDeprecationWarning
	  +-- SyntaxWarning
	  +-- OverflowWarning
	  +-- RuntimeWarning
	  +-- FutureWarning

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