12.2.9 Utilità varie

Ci sono varie utilità molto comode fornite con il package email.

quote( str): Restituisce una nuova stringa con i caratteri di backslashes ed i doppi apici in str preceduti da una (ulteriore) backslashes.

unquote( str): Restituisce una nuova stringa che è la versione non quotata di str. Se str termina ed inizia con dei doppi apici, questi vengono eliminati. In modo simile, se str termina ed inizia con delle parentesi angolari, queste vengono eliminate.

parseaddr( address): Analizza l'indirizzo, che deve essere il valore di alcuni campi contenenti indirizzi, come To: o Cc:, nelle sue parti costituenti, nome reale ed indirizzo email. Restituisce una tupla di queste informazioni, a meno che l'analisi non fallisca, nel qual caso viene restituita la tupla ('', '').

formataddr( pair): L'inverso di parseaddr(), questa riceve una tupla di 2 elementi nella forma (nome_reale, indirizzo_email) e restituisce un valore adatto per un header To: o Cc:. Se il primo degli elementi di pair (NdT: una coppia) è falso, viene restituito il secondo elemento non modificato.

getaddresses( fieldvalues)

Questo metodo restituisce una lista di tuple di 2 elementi nella forma restituita da codeparseaddr(). fieldvalues è una sequenza di valori di campi di intestazione come può essere restituita da Message.get_all(). Ecco un semplice esempio che prende tutti i recipienti di un messaggio:

from email.Utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

parsedate( date): Prova ad analizzare una data in accordo con le regole contenuto nella RFC 2822. Comunque, alcuni programmi di posta non seguono questo formato come specificato, perciò parsedate() prova ad indovinare correttamente in questi casi. date è una stringa contenente una data secondo la RFC 2822, come "Mon, 20 Nov 1995 19:12:08 -0500". Se ha successo nell'analisi, parsedate() restituisce una tupla di 9 elementi che può essere passata direttamente a time.mktime(); altrimenti viene restituito None. Notare che i campi 6, 7 e 8 della tupla restituita non sono utilizzabili.

parsedate_tz( date): Effettua la stessa funzione di parsedate(), ma restituisce None o una tupla di 10 elementi; i primi 9 elementi formano una tupla che può essere passata direttamente a time.mktime() e la decima è l'offset del timezone della data da UTC (che è il nome ufficiale di GMT, ovvero il Tempo medio di Greenwich)^12.2. Se la stringa in ingresso non ha una timezone, l'ultimo elemento della tupla restituita vale None. Notare che i campi 6, 7 e 8 del risultato non sono utilizzabili.

mktime_tz( tuple): Converte una tupla di 10 elementi come restituita da parsedate_tz() in un timestamp UTC. Se l'oggetto timezone nella tupla vale None, si assume come valore il tempo locale. Differenza minore: mktime_tz() interpreta i primi 8 elementi della tupla tuple come un tempo locale e poi compensa per la differenza di timezone. Questo può causare un piccolo errore intorno ai cambiamenti nell'ora legale, anche se non ci si deve preoccupare nell'uso comune.

formatdate( [timeval[, localtime]])

Restituisce una data come stringa come indicato dalla RFC 2822, per esempio:

Fri, 09 Nov 2001 01:08:47 -0000

Il parametro facoltativo timeval, se passato, è un valore in virgola mobile come accettato da time.gmtime() e time.localtime(), altrimenti viene utilizzato il tempo corrente.

Il parametro facoltativo localtime è un'opzione che, quando True, interpreta timeval e restituisce una data relativa al tempo locale invece di UTC, tenendo in debita considerazione l'ora legale. Il valore predefinito è False, a significare che viene utilizzato UTC.

make_msgid( [idstring]): Restituisce una stringa utilizzabile per un'intestazione Message-ID: compatibile con la RFC 2822. Il parametro facoltativo idstring, se passato, è una stringa utilizzata per rinforzare l'unicità dell'id del messaggio.

decode_rfc2231( s): Decodifica una stringa s in accordo con la RFC 2231.

encode_rfc2231( s[, charset[, language]]): Codifica la stringa s in accordo con la RFC 2231. I parametri facoltativi charset e language, se passati, sono l'insieme dei caratteri ed il nome della lingua da utilizzare. Se nessuno dei 2 viene passato, s viene restituita così com'è. Se charset viene passato, ma non language, la stringa viene codificata utilizzando una stringa vuota per language.

decode_params( params): Decodifica la lista di parametri in accordo con la RFC 2231. params è una sequenza di tuple di 2 elementi contenenti gli elementi nella forma (content-type, string-value).

Le seguenti funzioni sono considerate deprecate:

dump_address_pair( pair): Deprecato dalla versione 2.2.2 di Python. Usare invece formataddr().

decode( s): Deprecato dalla versione 2.2.2 di Python. Usare invece Header.decode_header().

encode( s[, charset[, encoding]]): Deprecato dalla versione 2.2.2 di Python. Usare invece Header.encode().

Footnotes

... Greenwich)^12.2: Notare che l'indicazione dell'offset della timezone è l'opposto del segno che indica la variabile time.timezone per la stessa timezone; la seconda variabile segue lo standard POSIX finché questo modulo è aderente alla RFC 2822.

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