Home       Trees       Indices       Help   
ProcImap v.2.0
Package ProcImap :: Module ImapMailbox :: Class ImapMailbox
[hide private]
[frames] | no frames]

Class ImapMailbox

source code

         object --+
                  |
mailbox.Mailbox --+
                  |
                 ImapMailbox

An abstract representation of a mailbox on an IMAP Server. This class implements the mailbox.Mailbox interface, insofar possible. Methods for changing a message in-place are not available for IMAP; the 'update' and '__setitem__' methods will raise a NotSupportedError. By default deleting messages (discard/remove) just adds the \Deleted flag to the message. Optionally, you can define a trash folder for any ImapMailbox. If set, "deleted" messages will be moved to the trash folder. Note that you must set the trash folder to '[Gmail]/Trash' if you are using Gmail, as the Gmail IMAP server has a different interpretation of what deletion means.

The class specific attributes are:

name name of the mailbox (readonly, see below) server ImapServer object (readonly, see below) trash Trash folder readonly True if mailbox is readonly, false otherwise

The 'trash' attribute may a string, another instance of ImapMailbox, or an instance of mailbox.Mailbox. If not set, it is None.

If the 'readonly' attribute is set, all subsequent calls that would change the mailbox will raise a ReadOnlyError. Note that setting the readonly attribute does not prevent you from making changes through the methods of the server attribute.

Instance Methods [hide private]
 
__init__(self, path, factory=<class ProcImap.ImapMessage.ImapMessage at 0x11206c0>, readonly=False, create=True)
Initialize an ImapMailbox path is a tuple with two elements, consisting of 1) an instance of ImapServer in any state 2) the name of a mailbox on the server as a string If the mailbox does not exist, it is created unless create is set to False, in which case NoSuchMailboxError is raised.		 source code
 
reconnect(self)
Renew the connection to the mailbox		 source code
 
switch(self, name, readonly=False, create=False)
Switch to a different Mailbox on the same server		 source code
 
search(self, criteria='ALL', charset=None)
Return a list of all the UIDs in the mailbox (as integers) that match the search criteria.		 source code
 
get_unseen_uids(self)
Get a list of all the unseen UIDs in the mailbox Equivalent to search(None, "UNSEEN UNDELETED")		 source code
 
get_all_uids(self)
Get a list of all the undeleted UIDs in the mailbox (as integers).		 source code
 
_cache_message(self, uid)
Download the RFC822 text of the message with UID and put in in the cache.		 source code
 
get_message(self, uid)
Return an ImapMessage object created from the message with UID.		 source code
 
__getitem__(self, uid)
Return an ImapMessage object created from the message with UID.		 source code
 
get(self, uid, default=None)
Return an ImapMessage object created from the message with UID.		 source code
 
get_string(self, uid)
Return a RFC822 string representation of the message corresponding to key, or raise a KeyError exception if no such message exists.		 source code
 
get_file(self, uid)
Return a cStringIO.StringIO of the message corresponding to key, or raise a KeyError exception if no such message exists.		 source code
 
has_key(self, uid)
Return True if key corresponds to a message, False otherwise.		 source code
 
__contains__(self, uid)
Return True if key corresponds to a message, False otherwise.		 source code
 
__len__(self)
Return a count of messages in the mailbox.		 source code
 
clear(self)
Delete all messages from the mailbox and expunge		 source code
 
pop(self, uid, default=None)
Return a representation of the message corresponding to key, delete and expunge the message.		 source code
 
popitem(self)
Return an arbitrary (key, message) pair, where key is a key and message is a message representation, delete and expunge the corresponding message.		 source code
 
update(self, arg=None)
Parameter arg should be a key-to-message mapping or an iterable of (key, message) pairs.		 source code
 
flush(self)
Equivalent to expunge()		 source code
 
lock(self)
Do nothing		 source code
 
unlock(self)
Do nothing		 source code
 
get_header(self, uid)
Return an ImapMessage object containing only the Header of the message with UID.		 source code
 
get_fields(self, uid, fields)
Return an mailbox.Message object containing only the requested header fields of the message with UID.		 source code
 
get_size(self, uid)
Get the number of bytes contained in the message with UID		 source code
 
get_imapflags(self, uid)
Return a list of imap flags for the message with UID Raise exception if there if there is no message with that UID.		 source code
 
get_internaldate(self, uid)
Return a time tuple representing the internal date for the message with UID Raise exception if there if there is no message with that UID.		 source code
 
__eq__(self, other)
Equality test: mailboxes are equal if they are equal in server and name		 source code
 
__ne__(self, other)
Inequality test: mailboxes are unequal if they are not equal		 source code
 
copy(self, uid, targetmailbox, exact=False)
Copy the message with UID to the targetmailbox and try to return the key that was assigned to the copied message in the targetmailbox.		 source code
 
move(self, uid, targetmailbox, exact=False)
Copy the message with UID to the targetmailbox, delete it in the original mailbox, and try to return the key that was assigned to the copied message in the targetmailbox.		 source code
 
discard(self, uid, exact=False)
If trash folder is defined, move the message with UID to trash and try to return the key assigned to the message in the trash; else, just add the \Deleted flag to the message with UID and return None.		 source code
 
remove(self, uid, exact=False)
Discard the message with UID.		 source code
 
__delitem__(self, uid)
Discard the message with UID.		 source code
 
__setitem__(self, uid, message)
Replace the message corresponding to key with message.		 source code
 
iterkeys(self)
Return an iterator over all UIDs This is an iterator over the list of UIDs at the time iterkeys() is a called.		 source code
 
keys(self)
Return a list of all UIDs		 source code
 
itervalues(self)
Return an iterator over all messages.		 source code
 
__iter__(self)
Return an iterator over all messages.		 source code
 
values(self)
Return a list of all messages The messages are represented as instances of ImapMessage unless a custom message factory was specified when the Mailbox instance was initialized.		 source code
 
iteritems(self)
Return an iterator over (uid, message) pairs, where uid is a key and message is a message representation.		 source code
 
items(self)
Return a list (uid, message) pairs, where uid is a key and message is a message representation.		 source code
 
add(self, message)
Add the message to mailbox.		 source code
 
add_imapflag(self, uid, *flags)
Add imap flag to message with UID.		 source code
 
remove_imapflag(self, uid, *flags)
Remove imap flags from message with UID		 source code
 
set_imapflags(self, uid, flags)
Set imap flags for message with UID flags must be an iterable of flags, or a string.		 source code
 
close(self)
Flush mailbox, close connection to server		 source code
 
expunge(self)
Expunge the mailbox (delete all messages marked for deletion)		 source code

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__

Inherited from mailbox.Mailbox (private): _dump_message

Properties [hide private]
  name
Name of the mailbox on the server
  server
Instance of the ImapServer that is being used as a backend

Inherited from object: __class__

Method Details [hide private]

__init__(self, path, factory=<class ProcImap.ImapMessage.ImapMessage at 0x11206c0>, readonly=False, create=True)
(Constructor)

source code 

Initialize an ImapMailbox path is a tuple with two elements, consisting of 1) an instance of ImapServer in any state 2) the name of a mailbox on the server as a string If the mailbox does not exist, it is created unless create is set to False, in which case NoSuchMailboxError is raised. The 'factory' parameter determines to which type the messages in the mailbox should be converted.

Note that two instances of ImapMailbox can never share the same instance of server. If you try to create an ImapMailbox with an instance of ImapServer that you already used for another mailbox, a ServerNotAvailableError will be thrown.

Overrides: mailbox.Mailbox.__init__

search(self, criteria='ALL', charset=None)

source code  
Return a list of all the UIDs in the mailbox (as integers)
    that match the search criteria. See documentation
    of imaplib and/or RFC3501 for details.
    Raise ImapNotOkError if a non-OK response is received from
    the server or if the response cannot be parsed into a list
    of integers.

    charset indicates the charset
    of the strings that appear in the search criteria.

    In all search keys that use strings, a message matches the key if
    the string is a substring of the field.  The matching is
    case-insensitive.

    The defined search keys are as follows.  Refer to RFC 3501 for detailed definitions of the
    arguments.

    <sequence set>
    ALL
    ANSWERED
    BCC <string>
    BEFORE <date>
    BODY <string>
    CC <string>
    DELETED
    DRAFT
    FLAGGED
    FROM <string>
    HEADER <field-name> <string>
    KEYWORD <flag>
    LARGER <n>
    NEW
    NOT <search-key>
    OLD
    ON <date>
    OR <search-key1> <search-key2>
    RECENT
    SEEN
    SENTBEFORE <date>
    SENTON <date>
    SENTSINCE <date>
    SINCE <date>
    SMALLER <n>
    SUBJECT <string>
    TEXT <string>
    TO <string>
    UID <sequence set>
    UNANSWERED
    UNDELETED
    UNDRAFT
    UNFLAGGED
    UNKEYWORD <flag>
    UNSEEN

Example:    search('FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"')
            search('TEXT "string not in mailbox"')

get_all_uids(self)

source code 

Get a list of all the undeleted UIDs in the mailbox (as integers). Equivalent to search(None, "UNDELETED")

_cache_message(self, uid)

source code 

Download the RFC822 text of the message with UID and put in in the cache. Return the RFC822 text of the message. If the message is already in the cache, it is returned directly. Raise KeyError if there if there is no message with that UID.

get_message(self, uid)

source code 

Return an ImapMessage object created from the message with UID. Raise KeyError if there if there is no message with that UID.

Overrides: mailbox.Mailbox.get_message

__getitem__(self, uid)
(Indexing operator)

source code 

Return an ImapMessage object created from the message with UID. Raise KeyError if there if there is no message with that UID.

Overrides: mailbox.Mailbox.__getitem__

get(self, uid, default=None)

source code 

Return an ImapMessage object created from the message with UID. Return default if there is no message with that UID.

Overrides: mailbox.Mailbox.get

get_string(self, uid)

source code 

Return a RFC822 string representation of the message corresponding to key, or raise a KeyError exception if no such message exists.

Overrides: mailbox.Mailbox.get_string

get_file(self, uid)

source code 

Return a cStringIO.StringIO of the message corresponding to key, or raise a KeyError exception if no such message exists.

Overrides: mailbox.Mailbox.get_file

has_key(self, uid)

source code 

Return True if key corresponds to a message, False otherwise.

Overrides: mailbox.Mailbox.has_key

__contains__(self, uid)
(In operator)

source code 

Return True if key corresponds to a message, False otherwise.

Overrides: mailbox.Mailbox.__contains__

__len__(self)
(Length operator)

source code 

Return a count of messages in the mailbox.

Overrides: mailbox.Mailbox.__len__

clear(self)

source code 

Delete all messages from the mailbox and expunge

Overrides: mailbox.Mailbox.clear

pop(self, uid, default=None)

source code 

Return a representation of the message corresponding to key, delete and expunge the message. If no such message exists, return default if it was supplied (i.e. is not None) or else raise a KeyError exception. The message is represented as an instance of ImapMessage unless a custom message factory was specified when the Mailbox instance was initialized.

Overrides: mailbox.Mailbox.pop

popitem(self)

source code 

Return an arbitrary (key, message) pair, where key is a key and message is a message representation, delete and expunge the corresponding message. If the mailbox is empty, raise a KeyError exception. The message is represented as an instance of ImapMessage unless a custom message factory was specified when the Mailbox instance was initialized.

Overrides: mailbox.Mailbox.popitem

update(self, arg=None)

source code 

Parameter arg should be a key-to-message mapping or an iterable of (key, message) pairs. Updates the mailbox so that, for each given key and message, the message corresponding to key is set to message as if by using __setitem__(). This operation is not supported for IMAP mailboxes and will raise NotSupportedError

Overrides: mailbox.Mailbox.update

flush(self)

source code 

Equivalent to expunge()

Overrides: mailbox.Mailbox.flush

lock(self)

source code 

Do nothing

Overrides: mailbox.Mailbox.lock

unlock(self)

source code 

Do nothing

Overrides: mailbox.Mailbox.unlock

get_header(self, uid)

source code 

Return an ImapMessage object containing only the Header of the message with UID. Raise KeyError if there if there is no message with that UID.

get_fields(self, uid, fields)

source code 

Return an mailbox.Message object containing only the requested header fields of the message with UID. The fields parameter is a string ofheader fields seperated by spaces, e.g. 'From SUBJECT date' Raise KeyError if there if there is no message with that UID.

copy(self, uid, targetmailbox, exact=False)

source code 

Copy the message with UID to the targetmailbox and try to return the key that was assigned to the copied message in the targetmailbox. If targetmailbox is an ImapMailbox, this is the target-UID. targetmailbox can be a string (the name of a mailbox on the same imap server), any of mailbox.Mailbox. Note that not all imap flags will be preserved if the targetmailbox is not on an ImapMailbox. Copying is efficient (i.e. the message is not downloaded) if the targetmailbox is on the same server. Do nothing and return None if there if there is no message with that UID. Unless 'exact' is set to True, the return value will be None if the targetmailbox is an ImapMailbox. This is because finding out the new UID of the copied message on an IMAP server is non-trivial. Giving 'exact' as True means that additional work will be done to find the accurate result. This operation can be relatively expensive. If targetmailbox is not an ImapMailbox, the value of 'exact' is irrelevant, and the return value will always be accurate.

move(self, uid, targetmailbox, exact=False)

source code 

Copy the message with UID to the targetmailbox, delete it in the original mailbox, and try to return the key that was assigned to the copied message in the targetmailbox. The discussions of the copy method concerning 'targetmailbox' and 'exact' apply here as well. Do nothing and return None if there if there is no message with that UID.

discard(self, uid, exact=False)

source code 

If trash folder is defined, move the message with UID to trash and try to return the key assigned to the message in the trash; else, just add the \Deleted flag to the message with UID and return None. If a trash folder is defined, this method is equivalent to self.move(uid, self.trash). The discussions of the move/copy method apply. Do nothing and return None if there if there is no message with that UID.

Overrides: mailbox.Mailbox.discard

remove(self, uid, exact=False)

source code 

Discard the message with UID. If there is no message with that UID, raise a KeyError This is exactly equivalent to self.discard(uid), except for the KeyError exception.

Overrides: mailbox.Mailbox.remove

__delitem__(self, uid)
(Index deletion operator)

source code 

Discard the message with UID. If there is no message with that UID, raise a KeyError

Overrides: mailbox.Mailbox.__delitem__

__setitem__(self, uid, message)
(Index assignment operator)

source code 

Replace the message corresponding to key with message. This operation is not supported for IMAP mailboxes and will raise NotSupportedError

Overrides: mailbox.Mailbox.__setitem__

iterkeys(self)

source code 

Return an iterator over all UIDs This is an iterator over the list of UIDs at the time iterkeys() is a called.

Overrides: mailbox.Mailbox.iterkeys

keys(self)

source code 

Return a list of all UIDs

Overrides: mailbox.Mailbox.keys

itervalues(self)

source code 

Return an iterator over all messages. The messages are represented as instances of ImapMessage unless a custom message factory was specified when the Mailbox instance was initialized.

Overrides: mailbox.Mailbox.itervalues

__iter__(self)

source code 

Return an iterator over all messages. Identical to itervalues

Overrides: mailbox.Mailbox.__iter__

values(self)

source code 

Return a list of all messages The messages are represented as instances of ImapMessage unless a custom message factory was specified when the Mailbox instance was initialized. Beware that this method can be extremely expensive in terms of time, bandwidth, and memory.

Overrides: mailbox.Mailbox.values

iteritems(self)

source code 

Return an iterator over (uid, message) pairs, where uid is a key and message is a message representation.

Overrides: mailbox.Mailbox.iteritems

items(self)

source code 

Return a list (uid, message) pairs, where uid is a key and message is a message representation. Beware that this method can be extremely expensive in terms of time, bandwidth, and memory.

Overrides: mailbox.Mailbox.items

add(self, message)

source code 

Add the message to mailbox. Message can be an instance of email.Message.Message (including instaces of mailbox.Message and its subclasses ); or an open file handle or a string containing an RFC822 message. Return the highest UID in the mailbox, which should be, but is not guaranteed to be, the UID of the message that was added. Raise ImapNotOkError if a non-OK response is received from the server

Overrides: mailbox.Mailbox.add

set_imapflags(self, uid, flags)

source code 

Set imap flags for message with UID flags must be an iterable of flags, or a string. If flags is a string, it is taken as the single flag to be set.

close(self)

source code 

Flush mailbox, close connection to server

Overrides: mailbox.Mailbox.close

Property Details [hide private]

name

Name of the mailbox on the server

Get Method:
unreachable(self)

server

Instance of the ImapServer that is being used as a backend

Get Method:
unreachable(self)

   Home       Trees       Indices       Help   
ProcImap v.2.0
Generated by Epydoc 3.0.1 on Fri Aug 6 18:48:54 2010 http://epydoc.sourceforge.net