12.2.6 Rappresentare l'insieme dei caratteri

Questo modulo fornisce una classe Charset per rappresentare l'insieme dei caratteri e le conversioni tra l'insieme di caratteri nei messaggi email, sia un registro dei charset ed alcuni convenienti metodi per manipolare questo registro. Le istanze di Charset vengono utilizzate in vari altri moduli nel package email.

Nuovo nella versione 2.2.2.

class Charset( [input_charset])

Mappa dell'insieme dei caratteri di email.

Questa classe fornisce informazioni circa i requisiti imposti alle email per uno specifico insieme di caratteri. Fornisce anche utili routine per convertire tra diversi insiemi di caratteri, fornendo la disponibilità dei codec applicabili. Fornendo un insieme di caratteri, farà del suo meglio per fornire informazioni su come utilizzare quel charset in un messaggio di email in modo confacente alle RFC.

Alcuni insiemi di caratteri devono essere codificati in quoted-printable o base64 quando utilizzati in intestazioni o nel corpo del messaggio. Alcuni insiemi di caratteri devono essere convertiti completamente e non sono ammessi nelle email.

Il parametro facoltativo input_charset viene descritto di seguito; viene sempre convertito in minuscolo. Dopo essere stato 'alias normalized' viene anche utilizzato per dare un'occhiata nel registro degli insiemi dei caratteri per trovare la codifica dell'intestazione, del corpo del messaggio ed il codec di conversione da utilizzare per l'insieme di caratteri. Per esempio, se input_charset è iso-8859-1, l'intestazione ed il corpo del messaggio verranno codificati utilizzando quoted-printable e non sarà necessario alcun codec di conversione per l'output. Se input_charset è euc-jp, l'intestazione verrà codificata in base64, il corpo non verrà codificato, ma il testo di output verrà convertito da euc-jp a iso-2022-jp.

Le istanze Charset hanno i seguenti attributi:

input_charset: L'insieme di caratteri specificato inizialmente. Gli alias comuni vengono convertiti nel loro nome ufficiale (per esempio, latin_1 viene convertito in iso-8859-1). Il valore predefinito è us-ascii a 7 bit.

header_encoding: Se l'insieme dei caratteri deve essere codificato prima che possa essere utilizzato nell'intestazione dell'email, questo attributo verrà impostato a Charset.QP (per quoted-printable), Charset.BASE64 (per la codifica base64) o Charset.SHORTEST per la codifica più breve tra QT e BASE64. Altrimenti varrà None.

body_encoding: Lo stesso di header_encoding, ma descrive la codifica per il corpo del messaggio, che effettivamente può essere differente dall'intestazione del messaggio. Charset.SHORTEST non è ammesso per body_encoding.

output_charset: Alcuni insiemi di caratteri devono essere convertiti prima di poterli utilizzare nelle intestazioni o nel corpo delle email. Se input_charset è uno di questi, questo attributo conterrà il nome dell'insieme dei caratteri in cui verrà convertito l'output. Altrimenti viene impostato a None.

input_codec: Il nome del codec Python utilizzato per convertire input_charset in Unicode. Se non è necessario alcun codec di conversione, questo attributo varrà None.

output_codec: Il nome del codec Python utilizzato per convertire Unicode in output_charset. Se non è necessario alcun codec di conversione, questo attributo avrà lo stesso valore di input_codec.

Le istanze Charset hanno anche i seguenti metodi:

get_body_encoding( )

Restituisce la codifica del trasferimento dei contenuti utilizzata per il corpo del messaggio.

Questo può essere sia la stringa "quoted-printable" che "base64", dipendentemente dalla codifica utilizzata, o è una funzione, nel qual caso si dovrà chiamare la funzione con un singolo argomento, l'oggetto Message che dovrà essere codificato. La funzione deve quindi impostare l'intestazione Content-Transfer-Encoding: ad un valore appropriato.

Restituisce la stringa "quoted-printable" se body_encoding è QP, restituisce la stringa "base64" se body_encoding è BASE64, altrimenti restituisce la stringa "7bit".

convert( s): Converte la stringa s da input_codec a output_codec.

to_splittable( s)

Converte una possibile stringa multibyte in un formato che possa essere diviso senza problemi. s è la stringa da dividere.

Utilizza input_codec per provare a convertire la stringa in Unicode, perciò può essere divisa senza problemi sui caratteri delimitativi (anche per caratteri multibyte).

Restituisce la stringa così com'è, se non sa come convertire s in Unicode con input_charset.

I caratteri che non possono essere convertiti in Unicode verranno sostituiti con il carattere Unicode di sostituzione "U+FFFD".

from_splittable( ustr[, to_output])

Converte una stringa divisibile in una stringa di codifica. ustr è la stringa unicode da ``ricomporre''.

Questo metodo utilizza il codec adeguato per provare a convertire la stringa da Unicode in un formato codificato. Restituisce la stringa così com'è se non è Unicode o se non può essere convertita da Unicode.

I caratteri che non possono essere convertiti da Unicode verranno sostituiti con un carattere appropriato (generalmente "?").

Se to_output è True (il caso predefinito), utilizza output_codec per convertire in un formato codificato. Se to_output è False, utilizza input_codec.

get_output_charset( ): Restituisce l'insieme dei caratteri di output.
Questo è l'attributo output_charset se non vale None, altrimenti è input_charset.

encoded_header_len( ): Restituisce la lunghezza della stringa di intestazione codificata, propriamente calcolata per le codifiche quoted-printable o base64.

header_encode( s[, convert])

L'intestazione codificata della stringa s.

Se convert è True, la stringa verrà convertita dall'insieme dei caratteri di input all'insieme dei caratteri di output in modo automatico. Questo non è utile per insiemi di caratteri multibyte, che hanno il problema della lunghezza delle righe (i charset multibyte devono essere divisi sul carattere, non un limite di byte); utilizzare la classe di alto livello Header per gestire questi problemi (vedere email.Header). Il valore predefinito di convert è convert False.

Il tipo di codifica (base64 o quoted-printable) sarà basata sull'attributo header_encoding.

body_encode( s[, convert])

Il corpo del messaggio codificato della stringa s.

Se convert è True (il caso predefinito), la stringa verrà automaticamente convertita dall'insieme dei caratteri di input all'insieme di caratteri di output. Al contrario di header_encode(), non ci sono problemi con i limiti di byte e gli insiemi di caratteri multibyte nel corpo dei messaggi, perciò è generalmente abbastanza sicuro.

Il tipo di codifica (base64 o quoted-printable) verrà basato sull'attributo body_encoding.

La classe Charset fornisce anche un numero di metodi per supportare le operazioni standard e funzioni built-in.

__str__( ): Restituisce input_charset come una stringa convertita in minuscolo. __repr__() è un alias per __str__().

__eq__( other): Questo metodo permette di confrontare due istanze di Charset per l'uguaglianza.

__ne__( other): Questo metodo permette di confrontare due istanze di Charset per la disuguaglianza.

Il modulo email.Charset fornisce anche le seguenti funzioni per aggiungere nuovi elementi all'insieme di caratteri globale, alias e registri dei codec:

add_charset( charset[, header_enc[, body_enc[, output_charset]]])

Aggiunge le proprietà dei caratteri al registro globale.

charset è il l'insieme dei caratteri di input e deve essere il nome canonico di un insieme di caratteri.

Gli argomenti facoltativi header_enc e body_enc possono essere sia Charset.QP per quoted-printable, Charset.BASE64 per la codifica base64, Charset.SHORTEST per la codifica più breve tra quoted-printable e base64 oppure None per nessuna codifica. SHORTEST è valida solo per header_enc. Il valore predefinito è None, ad indicare che non si desidera nessuna codifica.

Il parametro opzionale output_charset è l'insieme di caratteri in cui deve essere l'output. Le conversioni procederanno dall'insieme dei caratteri di input verso Unicode, verso l'insieme dei caratteri di output quando viene chiamato il metodo Charset.convert(). Il valore predefinito genera l'output nello stesso insieme di caratteri dell'input.

Sia input_charset che output_charset devono avere delle voci dei codec Unicode nella mappa di associazione dell'insieme dei caratteri nel modulo; utilizzare add_codec() per aggiungere codec di cui il modulo non è a conoscenza. Vedere la documentazione del modulo codecs per ulteriori informazioni.

Il registro degli insiemi dei caratteri globale viene mantenuto nel dizionario globale a livello di modulo CHARSETS.

add_alias( alias, canonical): Aggiunge un alias all'insieme dei caratteri. alias è il nome dell'alias, per esempio latin-1. canonical è il nome canonico dell'insieme dei caratteri, per esempio iso-8859-1.
Il registro globale degli alias degli insiemi dei caratteri viene mantenuto nel dizionario globale ALIASES.

add_codec( charset, codecname): Aggiunge un codec che mappa i caratteri nel charset fornito da e verso Unicode.
charset è il nome canonico dell'insieme dei caratteri. codecname è il nome del codec Python, come appropriato per il secondo argomento della funzione built-in unicode(), o per il metodo encode() di una stringa Unicode.

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