11.10.1 Oggetti IMAP4

Tutti i comandi IMAP4rev1 vengono rappresentati da metodi con lo stesso nome sia in maiuscolo che minuscolo.

Tutti gli argomenti per i comandi vengono convertiti in stringhe, eccetto che per "AUTHENTICATE", e l'ultimo argomento per "APPEND" che viene passato come letterale IMAP4. Se necessario (la stringa contiene caratteri sensibili per il protocollo IMAP4 e non è chiuso tra parentesi o doppie virgolette) ogni stringa viene quotata. Comunque, l'argomento password per il comando "LOGIN" viene sempre quotato. Se si vuole evitare di avere una stringa argomento quotata (per esempio: l'argomento flags per "STORE") includere la stringa tra parentesi (per esempio: r'(\Deleted)').

Ogni comando restituisce una tupla (type, [data, ...]) in cui type è abitualmente 'OK' o 'NO', e data è, sia il testo della risposta del comando, che il risultato generato dal comando. Ogni data è, sia una stringa, che una tupla. Se è una tupla, la prima parte è l'intestazione della risposta, e la seconda parte contiene i dati (per esempio: valore 'literal').

Una istanza IMAP4 ha i seguenti metodi:

append( mailbox, flags, date_time, message): Aggiunge messaggi alla casella indicata.

authenticate( func): Comando di autenticazione -- richiede l'analisi della riposta. Questo è attualmente non implementato, e solleva un'eccezione.

check( ): Verifica la mailbox sul server.

close( ): Chiude la mailbox correntemente selezionata. I messaggi cancellati vengono rimossi dalla mailbox scrivibile. Questo è il comando raccomandato prima del "LOGOUT".

copy( message_set, new_mailbox): Copia i messaggi message_set alla fine di new_mailbox.

create( mailbox): Crea una nuova mailbox chiamata mailbox.

delete( mailbox): Cancella la vecchia mailbox chiamata mailbox.

expunge( ): Rimuove permanentemente gli elementi cancellati dalla mailbox selezionata. Genera una risposta "EXPUNGE" per ogni messaggio cancellato. Il dato restituito contiene una lista di messaggi "EXPUNGE" numerati nell'ordine di ricezione.

fetch( message_set, message_parts): Scarica (una parte) dei messaggi. message_parts deve essere una stringa con il nome della parte del messaggio inclusa tra parentesi, per esempio: ""(UID BODY[TEXT])"". I dati restituiti sono tuple di parte dell'intestazione della busta e dei dati del messaggio.

getacl( mailbox): Ottiene le "ACL" per la mailbox. Questo metodo non è standard, ma è supportato dai server "Cyrus".

getquota( root): Ottiene il "quota" di utilizzo della risorse di root ed i limiti d'uso. Questo metodo è parte delle estensioni IMAP4 QUOTA definite nell'rfc2087. Nuovo nella versione 2.3.

getquotaroot( mailbox): Ottiene l'elenco di "quota" dei "root" per la mailbox indicata. Questo metodo è parte delle estensioni IMAP4 QUOTA definite nell'rfc2087. Nuovo nella versione 2.3.

list( [directory[, pattern]]): Elenca i nomi delle mailbox nella directory che corrisponde a pattern. La directory predefinita è la cartella di più alto livello ed il valore predefinito di pattern è verifica qualsiasi cosa. Restituisce i dati contenenti una lista di risposte "LIST".

login( user, password): Identifica il client utilizzando una password in testo piano. La password verrà quotata.

login_cram_md5( user, password): Forza l'utilizzo dell'autenticazione "CRAM-MD5" quando si identifica il cliente per proteggerne la password. Lavora solo se la risposta del server "CAPABILITY" include la frase "AUTH=CRAM-MD5". Nuovo nella versione 2.3.

logout( ): Chiude la connessione al server. Restituisce "BYE" come risposta del server.

lsub( [directory[, pattern]]): Elenca i nomi delle mailbox sottoscritte in directory corrispondenti a pattern. La directory predefinita è quella di livello massimo e il pattern predefinito corrisponde con tutte le mailbox. I dati restituiti sono tuple contenenti la parte dell'intestazione della busta del messaggio ed i dati del messaggio stesso.

noop( ): Invia "NOOP" al server.

open( host, port): Apre un socket sulla porta port dell'host. L'oggetto connessione, stabilito con questo metodo, verrà utilizzato nei metodi read, readline, send e shutdown. Questo metodo può essere sovrascritto.

partial( message_num, message_part, start, length): Scarica la parte troncata di un messaggio. Il dato restituito è una tupla della parte dell'intestazione della busta del messaggio e parte del corpo del messaggio stesso.

proxyauth( user): Esegue l'autenticazione come utente user. Permette ad un amministratore autorizzato di collegarsi alla casella di un utente. Nuovo nella versione 2.3.

read( size): Legge size bytes da un server remoto. Si può sovrascrivere questo metodo.

readline( ): Legge una riga da un server remoto. Si può sovrascrivere questo metodo.

recent( ): Invita il server per un aggiornamento. I dati restituiti sono None se non ci sono nuovi messaggi, altrimenti il valore della risposta "RECENT".

rename( oldmailbox, newmailbox): Rinomina la mailbox chiamata oldmailbox in newmailbox.

response( code): Restituisce i dati per il codice code di risposta quando ricevuto, altrimenti restituisce None. Restituisce il codice passato, al posto del tipo abituale.

search( charset, criterion[, ...])

Cerca la mailbox per il messaggio corrispondente. I dati restituiti contengono una lista separata da uno spazio dei numeri del messaggio rispondente. charset può essere None, nel cui caso nessun "CHARSET" verrà specificato nella richiesta al server. Il protocollo IMAP richiede che al massimo venga specificato un criterio; verrà sollevata un'eccezione quando il server restituisce un errore.

Esempio:

# M è un'istanza di IMAP4 connessa...
msgnums = M.search(None, 'FROM', '"LDJ"')

# o:
msgnums = M.search(None, '(FROM "LDJ")')

select( [mailbox[, readonly]]): Seleziona una mailbox. Il dato restituito è il conteggio dei messaggi nella mailbox (risposta "EXISTS"). La mailbox predefinita è 'INBOX'. Se l'opzione readonly viene impostata, non sono autorizzate modifiche alla mailbox.

send( data): Invia i dati data al server remoto. Questo metodo può essere sovrascritto.

setacl( mailbox, who, what): Imposta una "ACL" alla mailbox. Il metodo non è standard, ma è supportato dal server "Cyrus".

setquota( root, limits): Imposta il limite di "quota" limits delle risorse di root. Questo metodo fa parte delle estensioni IMAP4 QUOTA definite nell'rfc2087. Nuovo nella versione 2.3.

shutdown( ): Chiude una connessione stabilita con open. Questo metodo può essere sovrascritto.

socket( ): Restituisce l'istanza socket usata per la connessione al server.

sort( sort_criteria, charset, search_criterion[, ...])

Il comando sort è una variante di search con la semantica del sorting per il risultato. I dati restituiti contengono una lista separata da spazi dei numeri del messaggi corrispondenti.

Sort ha due argomenti prima dell'argomento/i search_criterion; una lista di sort_criteria tra parentesi ed il charset di ricerca. Notare che, diversamente da search, il parametro charset è obbligatorio. Esiste anche un comando uid sort che corrisponde a sort, alla stessa maniera di come uid search corrisponde a search. Il comando sort, prima cerca la mailbox per i messaggi che verificano il criterio di ricerca indicato usando l'argomento charset per l'interpretazione delle stringhe del criterio di ricerca. Restituisce il numero di messaggi corrispondenti.

Questo comando è previsto dall' estensione "IMAP4rev1".

status( mailbox, names): Richiede la condizione di stato named per la mailbox.

store( message_set, command, flag_list): Altera le opzioni di disposizione per i messaggi nella mailbox.

subscribe( mailbox): Sottoscrive una nuova mailbox.

thread( threading_algorithm, charset, search_criterion[, ...])

Il comando thread è una variante della ricerca search dei risultati, con semantica threading. I dati restituiti contengono una lista separata da spazi dei membri del thread.

I membri thread consistono in zero o più messaggi delimitati da spazi, che indicano successivi genitori e figli.

Thread possiede due argomenti prima dell'argomento/i search_criterion: un threading_algorithm ed il charset di ricerca. Notare che, diversamente da search, l'argomento di ricerca charset è obbligatorio. Esiste anche un comando uid thread corrispondente a thread, alla stessa maniera in cui uid search corrisponde a search. Il comando thread cerca per prima cosa le mailbox i cui messaggi trovino corrispondenza con il criterio di ricerca indicato usando l'argomento charset per l'interpretazione delle stringhe nel criterio di ricerca. Quindi restituisce i corrispondenti messaggi threaded in accordo con l'algoritmo di threading passato.

Questo è un comando di estensione "IMAP4rev1". Nuovo nella versione 2.4.

uid( command, arg[, ...]): Esegue i comandi in argomento con i messaggi identificati da UID, diversamente dal numero di messaggio. Restituisce la risposta appropriata al comando. Al massimo può essere indicato un argomento; se non ne vengono forniti, il server restituirà un errore e verrà sollevata un'eccezione.

unsubscribe( mailbox): Effettua la cancellazione di una sottoscrizione di una vecchia mailbox.

xatom( name[, arg[, ...]]): Consente semplici comandi di estensioni notificati dal server nella risposta "CAPABILITY".

Le istanze di IMAP4_SSL hanno solamente un metodo aggiuntivo:

ssl( ): Restituisce l'istanza SSLObject usata per le connessioni sicure al server.

I seguenti attributi vengono definiti sull'istanza di IMAP4:P4:

PROTOCOL_VERSION: Il protocollo più recente supportato nella risposta "CAPABILITY"del server.

debug: Valore intero per controllare la quantità di messaggi di debug. Il valore iniziale è preso dalla variabile Debug del modulo. Valori più grandi di 3 tracciano ogni comando.

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