| messages to be acted upon. It may be a simple message number (``'1'``), a range |
| of message numbers (``'2:4'``), or a group of non-contiguous ranges separated by |
| commas (``'1:3,6:9'``). A range can contain an asterisk to indicate an infinite |
| upper bound (``'3:*'``). |
| |
| An :class:`IMAP4` instance has the following methods: |
| |
| |
n | .. method:: XXX Class.append(mailbox, flags, date_time, message) |
n | .. method:: IMAP4.append(mailbox, flags, date_time, message) |
| |
| Append *message* to named mailbox. |
| |
| |
n | .. method:: XXX Class.authenticate(mechanism, authobject) |
n | .. method:: IMAP4.authenticate(mechanism, authobject) |
| |
| Authenticate command --- requires response processing. |
| |
| *mechanism* specifies which authentication mechanism is to be used - it should |
| appear in the instance variable ``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. |
| |
| |
n | .. method:: XXX Class.check() |
n | .. method:: IMAP4.check() |
| |
| Checkpoint mailbox on server. |
| |
| |
n | .. method:: XXX Class.close() |
n | .. method:: IMAP4.close() |
| |
| Close currently selected mailbox. Deleted messages are removed from writable |
| mailbox. This is the recommended command before ``LOGOUT``. |
| |
| |
n | .. method:: XXX Class.copy(message_set, new_mailbox) |
n | .. method:: IMAP4.copy(message_set, new_mailbox) |
| |
| Copy *message_set* messages onto end of *new_mailbox*. |
| |
| |
n | .. method:: XXX Class.create(mailbox) |
n | .. method:: IMAP4.create(mailbox) |
| |
| Create new mailbox named *mailbox*. |
| |
| |
n | .. method:: XXX Class.delete(mailbox) |
n | .. method:: IMAP4.delete(mailbox) |
| |
| Delete old mailbox named *mailbox*. |
| |
| |
n | .. method:: XXX Class.deleteacl(mailbox, who) |
n | .. method:: IMAP4.deleteacl(mailbox, who) |
| |
| Delete the ACLs (remove any rights) set for who on mailbox. |
| |
| .. versionadded:: 2.4 |
| |
| |
n | .. method:: XXX Class.expunge() |
n | .. method:: IMAP4.expunge() |
| |
| Permanently remove deleted items from selected mailbox. Generates an ``EXPUNGE`` |
| response for each deleted message. Returned data contains a list of ``EXPUNGE`` |
| message numbers in order received. |
| |
| |
n | .. method:: XXX Class.fetch(message_set, message_parts) |
n | .. method:: IMAP4.fetch(message_set, message_parts) |
| |
| Fetch (parts of) messages. *message_parts* should be a string of message part |
| names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``. Returned data |
| are tuples of message part envelope and data. |
| |
| |
n | .. method:: XXX Class.getacl(mailbox) |
n | .. method:: IMAP4.getacl(mailbox) |
| |
| Get the ``ACL``\ s for *mailbox*. The method is non-standard, but is supported |
| by the ``Cyrus`` server. |
| |
| |
n | .. method:: XXX Class.getannotation(mailbox, entry, attribute) |
n | .. method:: IMAP4.getannotation(mailbox, entry, attribute) |
| |
n | Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is non- |
n | Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is |
| standard, but is supported by the ``Cyrus`` server. |
| non-standard, but is supported by the ``Cyrus`` server. |
| |
| .. versionadded:: 2.5 |
| |
| |
n | .. method:: XXX Class.getquota(root) |
n | .. method:: IMAP4.getquota(root) |
| |
| Get the ``quota`` *root*'s resource usage and limits. This method is part of the |
| IMAP4 QUOTA extension defined in rfc2087. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. method:: XXX Class.getquotaroot(mailbox) |
n | .. method:: IMAP4.getquotaroot(mailbox) |
| |
| Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part |
| of the IMAP4 QUOTA extension defined in rfc2087. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. method:: XXX Class.list([directory[, pattern]]) |
n | .. method:: IMAP4.list([directory[, pattern]]) |
| |
| List mailbox names in *directory* matching *pattern*. *directory* defaults to |
| the top-level mail folder, and *pattern* defaults to match anything. Returned |
| data contains a list of ``LIST`` responses. |
| |
| |
n | .. method:: XXX Class.login(user, password) |
n | .. method:: IMAP4.login(user, password) |
| |
| Identify the client using a plaintext password. The *password* will be quoted. |
| |
| |
n | .. method:: XXX Class.login_cram_md5(user, password) |
n | .. method:: IMAP4.login_cram_md5(user, password) |
| |
| Force use of ``CRAM-MD5`` authentication when identifying the client to protect |
| the password. Will only work if the server ``CAPABILITY`` response includes the |
| phrase ``AUTH=CRAM-MD5``. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. method:: XXX Class.logout() |
n | .. method:: IMAP4.logout() |
| |
| Shutdown connection to server. Returns server ``BYE`` response. |
| |
| |
n | .. method:: XXX Class.lsub([directory[, pattern]]) |
n | .. method:: IMAP4.lsub([directory[, pattern]]) |
| |
| List subscribed mailbox names in directory matching pattern. *directory* |
| defaults to the top level directory and *pattern* defaults to match any mailbox. |
| Returned data are tuples of message part envelope and data. |
| |
| |
n | .. method:: XXX Class.myrights(mailbox) |
n | .. method:: IMAP4.myrights(mailbox) |
| |
| Show my ACLs for a mailbox (i.e. the rights that I have on mailbox). |
| |
| .. versionadded:: 2.4 |
| |
| |
n | .. method:: XXX Class.namespace() |
n | .. method:: IMAP4.namespace() |
| |
| Returns IMAP namespaces as defined in RFC2342. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. method:: XXX Class.noop() |
n | .. method:: IMAP4.noop() |
| |
| Send ``NOOP`` to server. |
| |
| |
n | .. method:: XXX Class.open(host, port) |
n | .. method:: IMAP4.open(host, port) |
| |
| Opens socket to *port* at *host*. The connection objects established by this |
| method will be used in the ``read``, ``readline``, ``send``, and ``shutdown`` |
| methods. You may override this method. |
| |
| |
n | .. method:: XXX Class.partial(message_num, message_part, start, length) |
n | .. method:: IMAP4.partial(message_num, message_part, start, length) |
| |
| Fetch truncated part of a message. Returned data is a tuple of message part |
| envelope and data. |
| |
| |
n | .. method:: XXX Class.proxyauth(user) |
n | .. method:: IMAP4.proxyauth(user) |
| |
| Assume authentication as *user*. Allows an authorised administrator to proxy |
| into any user's mailbox. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. method:: XXX Class.read(size) |
n | .. method:: IMAP4.read(size) |
| |
| Reads *size* bytes from the remote server. You may override this method. |
| |
| |
n | .. method:: XXX Class.readline() |
n | .. method:: IMAP4.readline() |
| |
| Reads one line from the remote server. You may override this method. |
| |
| |
n | .. method:: XXX Class.recent() |
n | .. method:: IMAP4.recent() |
| |
| Prompt server for an update. Returned data is ``None`` if no new messages, else |
| value of ``RECENT`` response. |
| |
| |
n | .. method:: XXX Class.rename(oldmailbox, newmailbox) |
n | .. method:: IMAP4.rename(oldmailbox, newmailbox) |
| |
| Rename mailbox named *oldmailbox* to *newmailbox*. |
| |
| |
n | .. method:: XXX Class.response(code) |
n | .. method:: IMAP4.response(code) |
| |
| Return data for response *code* if received, or ``None``. Returns the given |
| code, instead of the usual type. |
| |
| |
n | .. method:: XXX Class.search(charset, criterion[, ...]) |
n | .. method:: IMAP4.search(charset, criterion[, ...]) |
| |
| Search mailbox for matching messages. *charset* may be ``None``, in which case |
| no ``CHARSET`` will be specified in the request to the server. The IMAP |
| protocol requires that at least one criterion be specified; an exception will be |
| raised when the server returns an error. |
| |
| Example:: |
| |
| # M is a connected IMAP4 instance... |
| typ, msgnums = M.search(None, 'FROM', '"LDJ"') |
| |
| # or: |
| typ, msgnums = M.search(None, '(FROM "LDJ")') |
| |
| |
n | .. method:: XXX Class.select([mailbox[, readonly]]) |
n | .. method:: IMAP4.select([mailbox[, readonly]]) |
| |
| Select a mailbox. Returned data is the count of messages in *mailbox* |
| (``EXISTS`` response). The default *mailbox* is ``'INBOX'``. If the *readonly* |
| flag is set, modifications to the mailbox are not allowed. |
| |
| |
n | .. method:: XXX Class.send(data) |
n | .. method:: IMAP4.send(data) |
| |
| Sends ``data`` to the remote server. You may override this method. |
| |
| |
n | .. method:: XXX Class.setacl(mailbox, who, what) |
n | .. method:: IMAP4.setacl(mailbox, who, what) |
| |
| Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by |
| the ``Cyrus`` server. |
| |
| |
n | .. method:: XXX Class.setannotation(mailbox, entry, attribute[, ...]) |
n | .. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...]) |
| |
| Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is |
| supported by the ``Cyrus`` server. |
| |
| .. versionadded:: 2.5 |
| |
| |
n | .. method:: XXX Class.setquota(root, limits) |
n | .. method:: IMAP4.setquota(root, limits) |
| |
| Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4 |
| QUOTA extension defined in rfc2087. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. method:: XXX Class.shutdown() |
n | .. method:: IMAP4.shutdown() |
| |
| Close connection established in ``open``. You may override this method. |
| |
| |
n | .. method:: XXX Class.socket() |
n | .. method:: IMAP4.socket() |
| |
| Returns socket instance used to connect to server. |
| |
| |
n | .. method:: XXX Class.sort(sort_criteria, charset, search_criterion[, ...]) |
n | .. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...]) |
| |
| The ``sort`` command is a variant of ``search`` with sorting semantics for the |
| results. Returned data contains a space separated list of matching message |
| numbers. |
| |
| Sort has two arguments before the *search_criterion* argument(s); a |
| parenthesized list of *sort_criteria*, and the searching *charset*. Note that |
| unlike ``search``, the searching *charset* argument is mandatory. There is also |