The Mailbox interface is dictionary-like, with small keys
corresponding to messages. Keys are issued by the Mailbox instance
with which they will be used and are only meaningful to that Mailbox
instance. A key continues to identify a message even if the corresponding
message is modified, such as by replacing it with another message. Messages may
be added to a Mailbox instance using the set-like method
add() and removed using a del statement or the set-like methods
remove() and discard().
Mailbox interface semantics differ from dictionary semantics in some
noteworthy ways. Each time a message is requested, a new representation
(typically a Message instance) is generated, based upon the current
state of the mailbox. Similarly, when a message is added to a Mailbox
instance, the provided message representation's contents are copied. In neither
case is a reference to the message representation kept by the Mailbox
instance.
The default Mailbox iterator iterates over message representations, not
keys as the default dictionary iterator does. Moreover, modification of a
mailbox during iteration is safe and well-defined. Messages added to the
mailbox after an iterator is created will not be seen by the iterator. Messages
removed from the mailbox before the iterator yields them will be silently
skipped, though using a key from an iterator may result in a
KeyError exception if the corresponding message is subsequently
removed.
Mailbox itself is intended to define an interface and to be inherited
from by format-specific subclasses but is not intended to be instantiated.
Instead, you should instantiate a subclass.
Mailbox instances have the following methods:
add(
message)
Add message to the mailbox and return the key that has been assigned to
it.
Parameter message may be a Message instance, an
email.Message.Message instance, a string, or a file-like object (which
should be open in text mode). If message is an instance of the
appropriate format-specific Message subclass (e.g., if it's an
mboxMessage instance and this is an mbox instance), its
format-specific information is used. Otherwise, reasonable defaults for
format-specific information are used.
remove(
key)
__delitem__(
key)
discard(
key)
Delete the message corresponding to key from the mailbox.
If no such message exists, a KeyError exception is raised if the
method was called as remove() or __delitem__() but no
exception is raised if the method was called as discard(). The
behavior of discard() may be preferred if the underlying mailbox
format supports concurrent modification by other processes.
__setitem__(
key, message)
Replace the message corresponding to key with message. Raise a
KeyError exception if no message already corresponds to key.
As with add(), parameter message may be a Message
instance, an email.Message.Message instance, a string, or a file-like
object (which should be open in text mode). If message is an instance of
the appropriate format-specific Message subclass (e.g., if it's an
mboxMessage instance and this is an mbox instance), its
format-specific information is used. Otherwise, the format-specific information
of the message that currently corresponds to key is left unchanged.
iterkeys(
)
keys(
)
Return an iterator over all keys if called as iterkeys() or return a
list of keys if called as keys().
itervalues(
)
__iter__(
)
values(
)
Return an iterator over representations of all messages if called as
itervalues() or __iter__() or return a list of such
representations if called as values(). The messages are represented as
instances of the appropriate format-specific Message subclass unless a
custom message factory was specified when the Mailbox instance was
initialized. Note:
The behavior of __iter__() is unlike that of
dictionaries, which iterate over keys.
iteritems(
)
items(
)
Return an iterator over (key, message) pairs, where key is a
key and message is a message representation, if called as
iteritems() or return a list of such pairs if called as
items(). The messages are represented as instances of the appropriate
format-specific Message subclass unless a custom message factory was
specified when the Mailbox instance was initialized.
get(
key[, default=None])
__getitem__(
key)
Return a representation of the message corresponding to key. If no such
message exists, default is returned if the method was called as
get() and a KeyError exception is raised if the method was
called as __getitem__(). The message is represented as an instance of
the appropriate format-specific Message subclass unless a custom
message factory was specified when the Mailbox instance was
initialized.
get_message(
key)
Return a representation of the message corresponding to key as an
instance of the appropriate format-specific Message subclass, or raise
a KeyError exception if no such message exists.
get_string(
key)
Return a string representation of the message corresponding to key, or
raise a KeyError exception if no such message exists.
get_file(
key)
Return a file-like representation of the message corresponding to key,
or raise a KeyError exception if no such message exists. The
file-like object behaves as if open in binary mode. This file should be closed
once it is no longer needed.
Note:
Unlike other representations of messages, file-like representations are
not necessarily independent of the Mailbox instance that created them
or of the underlying mailbox. More specific documentation is provided by each
subclass.
has_key(
key)
__contains__(
key)
Return True if key corresponds to a message, False
otherwise.
__len__(
)
Return a count of messages in the mailbox.
clear(
)
Delete all messages from the mailbox.
pop(
key[, default])
Return a representation of the message corresponding to key and delete
the message. If no such message exists, return default if it was supplied
or else raise a KeyError exception. The message is represented as
an instance of the appropriate format-specific Message subclass unless
a custom message factory was specified when the Mailbox instance was
initialized.
popitem(
)
Return an arbitrary (key, message) pair, where key is a key
and message is a message representation, and delete the corresponding
message. If the mailbox is empty, raise a KeyError exception. The
message is represented as an instance of the appropriate format-specific
Message subclass unless a custom message factory was specified when the
Mailbox instance was initialized.
update(
arg)
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__(). As with
__setitem__(), each key must already correspond to a message in
the mailbox or else a KeyError exception will be raised, so in
general it is incorrect for arg to be a Mailbox instance.
Note:
Unlike with dictionaries, keyword arguments are not supported.
flush(
)
Write any pending changes to the filesystem. For some Mailbox
subclasses, changes are always written immediately and this method does
nothing.
lock(
)
Acquire an exclusive advisory lock on the mailbox so that other processes know
not to modify it. An ExternalClashError is raised if the lock is
not available. The particular locking mechanisms used depend upon the mailbox
format.
unlock(
)
Release the lock on the mailbox, if any.
close(
)
Flush the mailbox, unlock it if necessary, and close any open files. For some
Mailbox subclasses, this method does nothing.
