12.11.1 Oggetti Message

Un'istanza Message ha i seguenti metodi:

rewindbody( ): Posiziona all'inizio del corpo del messaggio. Questo funziona solamente se l'oggetto file consente la ricerca.

isheader( line): Restituisce la riga corrispondente al campo del nome in forma canonica (la chiave di dizionario che verrà utilizzata per indicizzarlo) se la riga è un'intestazione conforme a RFC 2822; altrimenti restituisce None (questo implica che l'analisi dovrebbe fermarsi qui e la riga dovrebbe essere respinta indietro nel flusso in input). Talvolta è utile sovrascrivere questo metodo in una sotto classe.

islast( line): Restituisce vero se la riga fornita è un delimitatore sul quale Message dovrebbe fermarsi. La riga di delimitazione viene eliminata ed il punto di lettura dell'oggetto file posizionato immediatamente dopo la riga stessa. Come comportamento predefinito questo metodo controlla semplicemente che la riga sia vuota, ma potete sovrascrivere tale comportamento in una sotto classe.

iscomment( line): Restituisce True se la riga fornita dovrebbe essere ignorata interamente, semplicemente saltata. Come comportamento predefinito restituisce sempre False, ma si può sovrascrivere tale comportamento in una sotto classe.

getallmatchingheaders( name): Restituisce una lista di righe composte da tutte le intestazioni che corrispondono al parametro name, se ve ne sono. Ogni riga fisica, indipendentemente dal fatto di essere una riga di continuazione oppure no, è un elemento separato della lista. Se nessuna intestazione corrisponde a name restituisce la lista vuota.

getfirstmatchingheader( name): Restituisce una lista di righe comprendente la prima intestazione corrispondente a name, e le sue righe di continuazione, nel caso ve ne siano. Restituisce None se non ci sono intestazioni corrispondenti a name.

getrawheader( name): Restituisce una singola stringa contenente il testo dopo i due punti nella prima intestazione corrispondente a name. Questo include gli spazi ad inizio stringa, il linefeed a fine stringa, i linefeed interni e gli spazi delle eventuali righe di continuazione. Restituisce None se non ci sono intestazioni corrispondenti a name.

getheader( name[, default]): Come getrawheader(name), ma elimina gli spazi in testa ed in coda. Gli spazi interni non vengono eliminati. L'argomento facoltativo default può essere utilizzato per specificare un differente valore predefinito come valore restituito, nel caso non ci siano intestazioni corrispondenti a name.

get( name[, default]): Un sinonimo per getheader(), per rendere l'interfaccia più compatibile con i dizionari regolari.

getaddr( name): Restituisce una coppia (nome completo, indirizzo email) risultante dall'analisi della stringa restituita da getheader(name). Se non esiste alcuna intestazione corrispondente a name, restituisce (None, None); altrimenti sia il nome completo che l'indirizzo sono stringhe (eventualmente vuote).
Esempio: se la prima intestazione From: di m contiene la stringa 'jack@cwi.nl (Jack Jansen)', allora m.getaddr('From') restituirà la coppia ('Jack Jansen', 'jack@cwi.nl'). Se l'intestazione avesse invece contenuto 'Jack Jansen <jack@cwi.nl>', sarebbe stato restituito esattamente lo stesso risultato.

getaddrlist( name): È simile al metodo getaddr(list), ma analizza un'intestazione che contiene una lista di indirizzi email (ad esempio un'intestazione To:) e restituisce una lista di coppie (nome completo, indirizzo email) (anche se l'intestazione contiene un solo indirizzo). Nel caso non ci sia nessuna intestazione corrispondente a name, restituisce una lista vuota.
Se ci fossero più intestazioni corrispondenti all'intestazione in analisi (ad esempio se ci fossero più intestazioni Cc:), verranno tutti analizzati per la ricerca degli indirizzi. Verranno analizzate anche tutte le eventuali righe di continuazione.

getdate( name): Recupera un'intestazione utilizzando getheader() e la analizza suddividendola in una tupla di nove elementi compatibile con time.mktime(); notare che i campi 6, 7 e 8 non sono utilizzabili. Se non ci fosse nessuna intestazione corrispondente a name, o non fosse analizzabile, restituisce None.
L'analisi delle date sembra essere un'arte oscura, e non tutti i server di posta aderiscono agli standard. Sebbene sia stata provata e riconosciuta corretta su un gran numero di messaggi email provenienti da fonti diverse, è tuttavia possibile che questa funzione possa occasionalmente produrre risultati non corretti.

getdate_tz( name): Recupera un'intestazione utilizzando getheader() e la analizza suddividendola in una tupla di dieci elementi; i primi 9 elementi formeranno una tupla compatibile con time.mktime(), ed il decimo sarà un numero che indica la differenza di fuso tra la zona della data e UTC. Notare che i campi 6, 7 e 8 non sono utilizzabili. In modo simile a getdate(), se non ci fosse nessuna intestazione corrispondente a name o fosse non analizzabile, restituisce None.

Le istanze Message supportano inoltre una interfaccia limitata di mappatura. In particolare: m[name] è simile a m.getheader(name) ma solleva l'eccezione KeyError se non ci sono intestazioni che corrispondono a name; e len(m), m.get(name[, default]), m.has_key(name), m.keys(), m.values() m.items(), e m.setdefault(name[, default]) si comportano come previsto, con la sola differenza che setdefault() utilizza una stringa vuota come valore predefinito. Le istanze di Message inoltre supportano l'interfaccia di mappatura scrivibile m[name] = value e del m[name]. Gli oggetti Message non supportano i metodi clear(), copy(), popitem() o update() dell'interfaccia di mappatura. Il supporto per get() e setdefault() è stato aggiunto solamente in Python 2.2.

Infine, le istanze Message hanno alcune variabili d'istanza pubbliche:

headers: Una lista che contiene l'intero insieme delle righe di intestazione, nell'ordine in cui sono state lette (con l'eccezione che le chiamate a setitem potrebbero influire su quest'ordine). Ogni linea viene terminata da un fine riga. La riga vuota che chiude le intestazioni non è contenuta nella lista.

fp: L'oggetto file o simile a file passato al momento dell'istanziazione. Questo può venire usato per leggere il contenuto del messaggio.

unixfrom: La riga Unix corrispondente a "From ", se il messaggio l'aveva, altrimenti una stringa vuota. Questo è necessario per rigenerare il messaggio in alcune circostanze, come per i file di mailbox in stile mbox.

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