4.9 codecs -- Registro dei codec e classi base

Questo modulo definisce le classi di base per i codec standard Python (encoder e decoder) e fornisce l'accesso al registro delle codifiche interno a Python, che gestisce le codifiche stesse e i processi di controllo della gestione degli errori.

Definisce le seguenti funzioni:

register( search_function)
Registra una funzione di ricerca codec. Le funzioni di ricerca si aspettano di ricevere un argomento, il nome da decodificare in lettere tutte minuscole, e restituisce una tupla di funzioni (encoder, decoder, stream_reader, stream_writer) prendendo i seguenti argomenti:

encoder e decoder: questi devono essere funzioni o metodi che possiedano la stessa interfaccia dei metodi encode()/decode() delle istanze di Codec (vedete Codec Interface). Le funzioni e i metodi si aspettano di lavorare in modalità stateless (NdT: senza stato).

stream_reader e stream_writer: questi hanno le funzioni factory che forniscono le seguenti interfacce:

factory(stream, errors='strict')

Le funzioni factory devono restituire oggetti che forniscano le interfacce definite rispettivamente dalle classi base StreamWriter e StreamReader. I codec dello stream (NdT: flusso) possono mantenere lo stato.

Valori possibili per gli errori sono 'strict' (solleva un'eccezione in caso di errore di codifica), 'replace' (sostituisce dati malformati con un accettabile marcatore di sostituzione, come un "?"), 'ignore' (ignora dati malformati e continua senza ulteriori notifiche), 'xmlcharrefreplace' (sostituisce con un appropriato riferimento a carattere XML (solo per la codifica)) e 'backslashreplace' (sostituisce con sequenze di escape indicate dal backslash (solo per la codifica)) qualsiasi altro errore di gestione, definito attraverso register_error().

Nel caso in cui una funzione di ricerca non trovi una data codifica, dovrebbe restituire None.

lookup( encoding)
Cerca una tupla di codec nel registro delle codifiche di Python, e restituisce la tupla della funzione, come indicato precedentemente.

Le decodifiche vengono prima cercate nella cache del registro. Se non trovate, viene controllata la lista delle funzioni di ricerca registrate. Se nessuna tupla di codec viene trovata, allora viene sollevata un'eccezione LookupError. Altrimenti, la tupla del codec viene inserita nella cache e restituita al chiamante.

Per semplificare l'accesso alle diverse codifiche, il modulo fornisce queste ulteriori funzioni che utilizzano lookup() per la loro ricerca:

getencoder( encoding)
Cerca un codec per il dato encoding, e restituisce la sua funzione di codifica.

Solleva un'eccezione LookupError nel caso in cui non possa trovare la codifica.

getdecoder( encoding)
Cerca un codec per il dato encoding, e restituisce la sua funzione di decodifica.

Solleva un'eccezione LookupError nel caso in cui non possa trovare la codifica.

getreader( encoding)
Cerca un codec per il dato encoding, e restituisce la sua classe StreamReader o la funzione factory.

Solleva un'eccezione LookupError nel caso in cui non possa trovare la codifica.

getwriter( encoding)
Cerca un codec per il dato encoding, e restituisce la sua classe StreamWriter o la funzione factory.

Solleva un'eccezione LookupError nel caso in cui non possa trovare la codifica.

register_error( name, error_handler)
Registra la funzione di gestione degli errori error_handler sotto il nome name. error_handler verrà chiamato durante la codifica e decodifica nel caso di un errore, quando name viene specificato come parametro d'errore.

Per la codifica, error_handler verrà chiamato con un'istanza UnicodeEncodeError, che contiene informazioni circa la posizione dell'errore. Il gestore dell'errore deve sollevare questa o una differente eccezione, o restituire una tupla con una sostituzione per la parte non codificabile dell'input, ed una posizione da cui la codifica possa continuare. Il codificatore codificherà la sostituzione, e continuerà la codifica dell'input originale alla posizione specificata. Valori di posizione negativi verranno considerati come relativi alla fine della stringa di input. Se la posizione risultante è fuori dai limiti, verrà sollevata un'eccezione IndexError.

Decodifica e traduzione lavorano in modo simile, eccetto per il fatto che UnicodeDecodeError o UnicodeTranslateError verranno passati al gestore, e che la sostituzione fornita dal gestore degli errori verrà inserita direttamente nell'output.

lookup_error( name)
Restituisce il gestore dell'errore precedentemente registrato sotto il nome name.

Solleva un'eccezione LookupError nel caso in cui non possa trovare il gestore.

strict_errors( exception)
Implementa una gestione dell'errore strict (NdT: rigorosa).

replace_errors( exception)
Implementa la gestione dell'errore replace.

ignore_errors( exception)
Implementa la gestione dell'errore ignore.

xmlcharrefreplace_errors_errors( exception)
Implementa la gestione dell'errore xmlcharrefreplace.

backslashreplace_errors_errors( exception)
Implementa la gestione dell'errore backslashreplace.

Per semplificare il lavoro con i file o i flussi codificati, il modulo definisce anche queste funzioni di utilità:

open( filename, mode[, encoding[, errors[, buffering]]])
Apre un file codificato usando il modo mode indicato, e ne restituisce un involucro per la versione in grado di fornire codifica e decodifica trasparenti.

Note: La versione realizzata con l'involucro accetterà solo il formato oggetto definito dai codec, per esempio, oggetti Unicode per la maggior parte dei codec built-in. Anche il risultato è dipendente dal codec e normalmente sarà Unicode.

encoding specifica la codifica che verrà usata per i file.

errors può venire indicata per definire la gestione degli errori. Predefinitamente viene considerata 'strict', che solleverà un'eccezione ValueError nel caso in cui si verifichino errori di codifica.

buffering ha lo stesso significato della funzione built-in open(). La sua impostazione predefinita è una riga bufferizzata.

EncodedFile( file, input[, output[, errors]])
Restituisce una versione realizzata mediante un involucro del file, che fornisce in modo trasparente la traduzione di codifica.

Stringhe scritte nel file realizzato mediante involucro vengono interpretate in accordo all'input di codifica indicato, e quindi scritte nel file originale come stringhe utilizzando la codifica output. La codifica intermedia sarà tipicamente Unicode, ma questo dipende dai codec specificati.

Se output non viene indicato, il suo valore predefinito sarà input.

errors può venire indicato per definire la gestione degli errori. Il suo valore predefinito è 'strict', che solleva un'eccezione ValueError nel caso in cui venga rilevato un errore di codifica.

Il modulo fornisce anche le seguenti costanti, utili per leggere e scrivere su file dipendenti dalla piattaforma:

BOM
BOM_BE
BOM_LE
BOM_UTF8
BOM_UTF16
BOM_UTF16_BE
BOM_UTF16_LE
BOM_UTF32
BOM_UTF32_BE
BOM_UTF32_LE
Queste costanti definiscono diverse codifiche del byte order mark (BOM) Unicode, usato nei flussi di dati in UTF-16 e UTF-32 per indicare il byte order utilizzato nello stream o nel file, ed in UTF-8 come firma Unicode. BOM_UTF16 è sia BOM_UTF16_BE che BOM_UTF16_LE, a seconda del byte order nativo della piattaforma, BOM è un alias per BOM_UTF16, BOM_LE per BOM_UTF16_LE e BOM_BE per BOM_UTF16_BE. Gli altri rappresentano il BOM nelle codifiche UTF-8 e UTF-32.



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