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'.