imaplib :: IMAP4 :: Class IMAP4
[hide private]
[frames] | no frames]

Class IMAP4

source code

Known Subclasses:
IMAP4_SSL, IMAP4_stream

IMAP4 client class.

Instantiate with: IMAP4([host[, port]])

        host - host's name (default: localhost);
        port - port number (default: standard IMAP4 port).

All IMAP4rev1 commands are supported by methods of the same
name (in lower-case).

All arguments to commands are converted to strings, except for
AUTHENTICATE, and the last argument to APPEND which is passed as
an IMAP4 literal.  If necessary (the string contains any
non-printing characters or white-space and isn't enclosed with
either parentheses or double quotes) each string is quoted.
However, the 'password' argument to the LOGIN command is always
quoted.  If you want to avoid having an argument string quoted
(eg: the 'flags' argument to STORE) then enclose the string in
parentheses (eg: "(\Deleted)").

Each command returns a tuple: (type, [data, ...]) where 'type'
is usually 'OK' or 'NO', and 'data' is either the text from the
tagged response, or untagged results from command. Each 'data'
is either a string, or a tuple. If a tuple, then the first part
is the header of the response, and the second part contains
the data (ie: 'literal' value).

Errors raise the exception class <instance>.error("<reason>").
IMAP4 server errors raise <instance>.abort("<reason>"),
which is a sub-class of 'error'. Mailbox status changes
from READ-WRITE to READ-ONLY raise the exception class
<instance>.readonly("<reason>"), which is a sub-class of 'abort'.

"error" exceptions imply a program error.
"abort" exceptions imply the connection should be reset, and
        the command re-tried.
"readonly" exceptions imply the command should be re-tried.

Note: to use this module, you must read the RFCs pertaining to the
IMAP4 protocol, as the semantics of the arguments to each IMAP4
command are left to the invoker, not to mention the results. Also,
most IMAP servers implement a sub-set of the commands available here.



Nested Classes [hide private]
  abort
  error
  readonly
Instance Methods [hide private]
 
_CRAM_MD5_AUTH(self, challenge)
Authobject to use with CRAM-MD5 authentication.
source code
 
__getattr__(self, attr) source code
 
__init__(self, host='', port=143) source code
 
_append_untagged(self, typ, dat) source code
 
_check_bye(self) source code
 
_checkquote(self, arg) source code
 
_command(self, name, *args) source code
 
_command_complete(self, name, tag) source code
 
_dump_ur(self, dict) source code
 
_get_line(self) source code
 
_get_response(self) source code
 
_get_tagged_response(self, tag) source code
 
_log(self, line) source code
 
_match(self, cre, s) source code
 
_mesg(self, s, secs=global_settings.applications_parent) source code
 
_new_tag(self) source code
 
_quote(self, arg) source code
 
_simple_command(self, name, *args) source code
 
_untagged_response(self, typ, dat, name) source code
 
append(self, mailbox, flags, date_time, message)
Append message to named mailbox.
source code
 
authenticate(self, mechanism, authobject)
Authenticate command - requires response processing.
source code
 
capability(self)
(typ, [data]) = <instance>.capability() Fetch capabilities list from server.
source code
 
check(self)
Checkpoint mailbox on server.
source code
 
close(self)
Close currently selected mailbox.
source code
 
copy(self, message_set, new_mailbox)
Copy 'message_set' messages onto end of 'new_mailbox'.
source code
 
create(self, mailbox)
Create new mailbox.
source code
 
delete(self, mailbox)
Delete old mailbox.
source code
 
deleteacl(self, mailbox, who)
Delete the ACLs (remove any rights) set for who on mailbox.
source code
 
expunge(self)
Permanently remove deleted items from selected mailbox.
source code
 
fetch(self, message_set, message_parts)
Fetch (parts of) messages.
source code
 
getacl(self, mailbox)
Get the ACLs for a mailbox.
source code
 
getannotation(self, mailbox, entry, attribute)
(typ, [data]) = <instance>.getannotation(mailbox, entry, attribute) Retrieve ANNOTATIONs.
source code
 
getquota(self, root)
Get the quota root's resource usage and limits.
source code
 
getquotaroot(self, mailbox)
Get the list of quota roots for the named mailbox.
source code
 
list(self, directory='""', pattern='*')
List mailbox names in directory matching pattern.
source code
 
login(self, user, password)
Identify client using plaintext password.
source code
 
login_cram_md5(self, user, password)
Force use of CRAM-MD5 authentication.
source code
 
logout(self)
Shutdown connection to server.
source code
 
lsub(self, directory='""', pattern='*')
List 'subscribed' mailbox names in directory matching pattern.
source code
 
myrights(self, mailbox)
Show my ACLs for a mailbox (i.e.
source code
 
namespace(self)
Returns IMAP namespaces ala rfc2342
source code
 
noop(self)
Send NOOP command.
source code
 
open(self, host='', port=143)
Setup connection to remote server on "host:port" (default: localhost:standard IMAP4 port).
source code
 
partial(self, message_num, message_part, start, length)
Fetch truncated part of a message.
source code
 
print_log(self) source code
 
proxyauth(self, user)
Assume authentication as "user".
source code
 
read(self, size)
Read 'size' bytes from remote.
source code
 
readline(self)
Read line from remote.
source code
 
recent(self)
Return most recent 'RECENT' responses if any exist, else prompt server for an update using the 'NOOP' command.
source code
 
rename(self, oldmailbox, newmailbox)
Rename old mailbox name to new.
source code
 
response(self, code)
Return data for response 'code' if received, or None.
source code
 
search(self, charset, *criteria)
Search mailbox for matching messages.
source code
 
select(self, mailbox='INBOX', readonly=True)
Select a mailbox.
source code
 
send(self, data)
Send data to remote.
source code
 
setacl(self, mailbox, who, what)
Set a mailbox acl.
source code
 
setannotation(self, *args)
(typ, [data]) = <instance>.setannotation(mailbox[, entry, attribute]+) Set ANNOTATIONs.
source code
 
setquota(self, root, limits)
Set the quota root's resource limits.
source code
 
shutdown(self)
Close I/O established in "open".
source code
 
socket(self)
Return socket instance used to connect to IMAP4 server.
source code
 
sort(self, sort_criteria, charset, *search_criteria)
IMAP4rev1 extension SORT command.
source code
 
status(self, mailbox, names)
Request named status conditions for mailbox.
source code
 
store(self, message_set, command, flags)
Alters flag dispositions for messages in mailbox.
source code
 
subscribe(self, mailbox)
Subscribe to new mailbox.
source code
 
thread(self, threading_algorithm, charset, *search_criteria)
IMAPrev1 extension THREAD command.
source code
 
uid(self, command, *args)
Execute "command arg ..." with messages identified by UID, rather than message number.
source code
 
unsubscribe(self, mailbox)
Unsubscribe from old mailbox.
source code
 
xatom(self, name, *args)
Allow simple extension commands notified by server in CAPABILITY response.
source code
Class Variables [hide private]
  mustquote = re.compile(r'[^\w!#\$%&\'\*\+,\.:;<=>\?\^`\|~-]')
Method Details [hide private]

append(self, mailbox, flags, date_time, message)

source code 
Append message to named mailbox.

(typ, [data]) = <instance>.append(mailbox, flags, date_time, message)

        All args except `message' can be None.

authenticate(self, mechanism, authobject)

source code 
Authenticate command - requires response processing.

'mechanism' specifies which authentication mechanism is to
be used - it must appear in <instance>.capabilities in the
form AUTH=<mechanism>.

'authobject' must be a callable object:

        data = authobject(response)

It will be called to process server continuation responses.
It should return data that will be encoded and sent to server.
It should return None if the client abort response '*' should
be sent instead.

check(self)

source code 

Checkpoint mailbox on server.

(typ, [data]) = <instance>.check()

close(self)

source code 

Close currently selected mailbox.

Deleted messages are removed from writable mailbox. This is the recommended command before 'LOGOUT'.

(typ, [data]) = <instance>.close()

copy(self, message_set, new_mailbox)

source code 

Copy 'message_set' messages onto end of 'new_mailbox'.

(typ, [data]) = <instance>.copy(message_set, new_mailbox)

create(self, mailbox)

source code 

Create new mailbox.

(typ, [data]) = <instance>.create(mailbox)

delete(self, mailbox)

source code 

Delete old mailbox.

(typ, [data]) = <instance>.delete(mailbox)

deleteacl(self, mailbox, who)

source code 

Delete the ACLs (remove any rights) set for who on mailbox.

(typ, [data]) = <instance>.deleteacl(mailbox, who)

expunge(self)

source code 

Permanently remove deleted items from selected mailbox.

Generates 'EXPUNGE' response for each deleted message.

(typ, [data]) = <instance>.expunge()

'data' is list of 'EXPUNGE'd message numbers in order received.

fetch(self, message_set, message_parts)

source code 

Fetch (parts of) messages.

(typ, [data, ...]) = <instance>.fetch(message_set, message_parts)

'message_parts' should be a string of selected parts enclosed in parentheses, eg: "(UID BODY[TEXT])".

'data' are tuples of message part envelope and data.

getacl(self, mailbox)

source code 

Get the ACLs for a mailbox.

(typ, [data]) = <instance>.getacl(mailbox)

getquota(self, root)

source code 

Get the quota root's resource usage and limits.

Part of the IMAP4 QUOTA extension defined in rfc2087.

(typ, [data]) = <instance>.getquota(root)

getquotaroot(self, mailbox)

source code 

Get the list of quota roots for the named mailbox.

(typ, [[QUOTAROOT responses...], [QUOTA responses]]) = <instance>.getquotaroot(mailbox)

list(self, directory='""', pattern='*')

source code 

List mailbox names in directory matching pattern.

(typ, [data]) = <instance>.list(directory='""', pattern='*')

'data' is list of LIST responses.

login(self, user, password)

source code 

Identify client using plaintext password.

(typ, [data]) = <instance>.login(user, password)

NB: 'password' will be quoted.

login_cram_md5(self, user, password)

source code 

Force use of CRAM-MD5 authentication.

(typ, [data]) = <instance>.login_cram_md5(user, password)

logout(self)

source code 

Shutdown connection to server.

(typ, [data]) = <instance>.logout()

Returns server 'BYE' response.

lsub(self, directory='""', pattern='*')

source code 

List 'subscribed' mailbox names in directory matching pattern.

(typ, [data, ...]) = <instance>.lsub(directory='""', pattern='*')

'data' are tuples of message part envelope and data.

myrights(self, mailbox)

source code 

Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).

(typ, [data]) = <instance>.myrights(mailbox)

namespace(self)

source code 

Returns IMAP namespaces ala rfc2342

(typ, [data, ...]) = <instance>.namespace()

noop(self)

source code 

Send NOOP command.

(typ, [data]) = <instance>.noop()

open(self, host='', port=143)

source code 
Setup connection to remote server on "host:port"
    (default: localhost:standard IMAP4 port).
This connection will be used by the routines:
    read, readline, send, shutdown.

partial(self, message_num, message_part, start, length)

source code 

Fetch truncated part of a message.

(typ, [data, ...]) = <instance>.partial(message_num, message_part, start, length)

'data' is tuple of message part envelope and data.

proxyauth(self, user)

source code 

Assume authentication as "user".

Allows an authorised administrator to proxy into any user's mailbox.

(typ, [data]) = <instance>.proxyauth(user)

recent(self)

source code 

Return most recent 'RECENT' responses if any exist, else prompt server for an update using the 'NOOP' command.

(typ, [data]) = <instance>.recent()

'data' is None if no new messages, else list of RECENT responses, most recent last.

rename(self, oldmailbox, newmailbox)

source code 

Rename old mailbox name to new.

(typ, [data]) = <instance>.rename(oldmailbox, newmailbox)

response(self, code)

source code 

Return data for response 'code' if received, or None.

Old value for response 'code' is cleared.

(code, [data]) = <instance>.response(code)

search(self, charset, *criteria)

source code 

Search mailbox for matching messages.

(typ, [data]) = <instance>.search(charset, criterion, ...)

'data' is space separated list of matching message numbers.

select(self, mailbox='INBOX', readonly=True)

source code 

Select a mailbox.

Flush all untagged responses.

(typ, [data]) = <instance>.select(mailbox='INBOX', readonly=False)

'data' is count of messages in mailbox ('EXISTS' response).

Mandated responses are ('FLAGS', 'EXISTS', 'RECENT', 'UIDVALIDITY'), so other responses should be obtained via <instance>.response('FLAGS') etc.

setacl(self, mailbox, who, what)

source code 

Set a mailbox acl.

(typ, [data]) = <instance>.setacl(mailbox, who, what)

setquota(self, root, limits)

source code 

Set the quota root's resource limits.

(typ, [data]) = <instance>.setquota(root, limits)

socket(self)

source code 

Return socket instance used to connect to IMAP4 server.

socket = <instance>.socket()

sort(self, sort_criteria, charset, *search_criteria)

source code 

IMAP4rev1 extension SORT command.

(typ, [data]) = <instance>.sort(sort_criteria, charset, search_criteria, ...)

status(self, mailbox, names)

source code 

Request named status conditions for mailbox.

(typ, [data]) = <instance>.status(mailbox, names)

store(self, message_set, command, flags)

source code 

Alters flag dispositions for messages in mailbox.

(typ, [data]) = <instance>.store(message_set, command, flags)

subscribe(self, mailbox)

source code 

Subscribe to new mailbox.

(typ, [data]) = <instance>.subscribe(mailbox)

thread(self, threading_algorithm, charset, *search_criteria)

source code 

IMAPrev1 extension THREAD command.

(type, [data]) = <instance>.thread(threading_alogrithm, charset, search_criteria, ...)

uid(self, command, *args)

source code 
Execute "command arg ..." with messages identified by UID,
        rather than message number.

(typ, [data]) = <instance>.uid(command, arg1, arg2, ...)

Returns response appropriate to 'command'.

unsubscribe(self, mailbox)

source code 

Unsubscribe from old mailbox.

(typ, [data]) = <instance>.unsubscribe(mailbox)

xatom(self, name, *args)

source code 
Allow simple extension commands
        notified by server in CAPABILITY response.

Assumes command is legal in current state.

(typ, [data]) = <instance>.xatom(name, arg, ...)

Returns response appropriate to extension command `name'.