mailbox --- Manipulate mailboxes in various formats — Mailbox objects

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.

The !Mailbox class supports the with statement. When used as a context manager, !Mailbox calls lock when the context is entered, returns the mailbox object as the context object, and at context end calls close, thereby releasing the lock.

!Mailbox instances have the following methods