7.3.1 Mailbox objects

##
7.3.1 `Mailbox` objects

class `Mailbox`
  A mailbox, which may be inspected and modified.

The `Mailbox` class defines an interface and is not intended to be instantiated. Instead, format-specific subclasses should inherit from `Mailbox` and your code should instantiate a particular subclass.

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.

Warning: Be very cautious when modifying mailboxes that might be simultaneously changed by some other process. The safest mailbox format to use for such tasks is Maildir; try to avoid using single-file formats such as mbox for concurrent writing. If you're modifying a mailbox, you must lock it by calling the `lock()` and `unlock()` methods before reading any messages in the file or making any changes by adding or deleting a message. Failing to lock the mailbox runs the risk of losing messages or corrupting the entire mailbox.

`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 `flush()` does nothing, but you should still make a habit of calling this method.

`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. You should always lock the mailbox before making any modifications to its contents.

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