diff options
Diffstat (limited to 'Doc/library/mailbox.rst')
| -rw-r--r-- | Doc/library/mailbox.rst | 1264 |
1 files changed, 644 insertions, 620 deletions
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 7cc2923..38765ed 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -32,238 +32,244 @@ Maildir, mbox, MH, Babyl, and MMDF. A mailbox, which may be inspected and modified. -The :class:`Mailbox` class defines an interface and is not intended to be -instantiated. Instead, format-specific subclasses should inherit from -:class:`Mailbox` and your code should instantiate a particular subclass. + The :class:`Mailbox` class defines an interface and is not intended to be + instantiated. Instead, format-specific subclasses should inherit from + :class:`Mailbox` and your code should instantiate a particular subclass. + + The :class:`Mailbox` interface is dictionary-like, with small keys + corresponding to messages. Keys are issued by the :class:`Mailbox` instance + with which they will be used and are only meaningful to that :class:`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 :class:`Mailbox` instance using the set-like + method :meth:`add` and removed using a ``del`` statement or the set-like + methods :meth:`remove` and :meth:`discard`. + + :class:`Mailbox` interface semantics differ from dictionary semantics in some + noteworthy ways. Each time a message is requested, a new representation + (typically a :class:`Message` instance) is generated based upon the current + state of the mailbox. Similarly, when a message is added to a + :class:`Mailbox` instance, the provided message representation's contents are + copied. In neither case is a reference to the message representation kept by + the :class:`Mailbox` instance. + + The default :class:`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 + :exc:`KeyError` exception if the corresponding message is subsequently + removed. -The :class:`Mailbox` interface is dictionary-like, with small keys corresponding -to messages. Keys are issued by the :class:`Mailbox` instance with which they -will be used and are only meaningful to that :class:`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 :class:`Mailbox` instance using the set-like method -:meth:`add` and removed using a ``del`` statement or the set-like methods -:meth:`remove` and :meth:`discard`. - -:class:`Mailbox` interface semantics differ from dictionary semantics in some -noteworthy ways. Each time a message is requested, a new representation -(typically a :class:`Message` instance) is generated based upon the current -state of the mailbox. Similarly, when a message is added to a :class:`Mailbox` -instance, the provided message representation's contents are copied. In neither -case is a reference to the message representation kept by the :class:`Mailbox` -instance. + .. warning:: -The default :class:`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 :exc:`KeyError` exception if -the corresponding message is subsequently removed. + 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 :meth:`lock` and :meth:`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. -.. warning:: + :class:`Mailbox` instances have the following methods: - 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 - :meth:`lock` and :meth:`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. -:class:`Mailbox` instances have the following methods: + .. method:: add(message) + Add *message* to the mailbox and return the key that has been assigned to + it. -.. method:: Mailbox.add(message) + Parameter *message* may be a :class:`Message` instance, an + :class:`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 :class:`Message` subclass (e.g., if it's an + :class:`mboxMessage` instance and this is an :class:`mbox` instance), its + format-specific information is used. Otherwise, reasonable defaults for + format-specific information are used. - Add *message* to the mailbox and return the key that has been assigned to it. - Parameter *message* may be a :class:`Message` instance, an - :class:`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 :class:`Message` subclass (e.g., if it's an :class:`mboxMessage` - instance and this is an :class:`mbox` instance), its format-specific information - is used. Otherwise, reasonable defaults for format-specific information are - used. + .. method:: remove(key) + __delitem__(key) + discard(key) + Delete the message corresponding to *key* from the mailbox. -.. method:: Mailbox.remove(key) - Mailbox.__delitem__(key) - Mailbox.discard(key) + If no such message exists, a :exc:`KeyError` exception is raised if the + method was called as :meth:`remove` or :meth:`__delitem__` but no + exception is raised if the method was called as :meth:`discard`. The + behavior of :meth:`discard` may be preferred if the underlying mailbox + format supports concurrent modification by other processes. - Delete the message corresponding to *key* from the mailbox. - If no such message exists, a :exc:`KeyError` exception is raised if the method - was called as :meth:`remove` or :meth:`__delitem__` but no exception is raised - if the method was called as :meth:`discard`. The behavior of :meth:`discard` may - be preferred if the underlying mailbox format supports concurrent modification - by other processes. + .. method:: __setitem__(key, message) + Replace the message corresponding to *key* with *message*. Raise a + :exc:`KeyError` exception if no message already corresponds to *key*. -.. method:: Mailbox.__setitem__(key, message) + As with :meth:`add`, parameter *message* may be a :class:`Message` + instance, an :class:`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 :class:`Message` subclass + (e.g., if it's an :class:`mboxMessage` instance and this is an + :class:`mbox` instance), its format-specific information is + used. Otherwise, the format-specific information of the message that + currently corresponds to *key* is left unchanged. - Replace the message corresponding to *key* with *message*. Raise a - :exc:`KeyError` exception if no message already corresponds to *key*. - As with :meth:`add`, parameter *message* may be a :class:`Message` instance, an - :class:`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 :class:`Message` subclass (e.g., if it's an :class:`mboxMessage` - instance and this is an :class:`mbox` instance), its format-specific information - is used. Otherwise, the format-specific information of the message that - currently corresponds to *key* is left unchanged. + .. method:: iterkeys() + keys() + Return an iterator over all keys if called as :meth:`iterkeys` or return a + list of keys if called as :meth:`keys`. -.. method:: Mailbox.iterkeys() - Mailbox.keys() - Return an iterator over all keys if called as :meth:`iterkeys` or return a list - of keys if called as :meth:`keys`. + .. method:: itervalues() + __iter__() + values() + Return an iterator over representations of all messages if called as + :meth:`itervalues` or :meth:`__iter__` or return a list of such + representations if called as :meth:`values`. The messages are represented + as instances of the appropriate format-specific :class:`Message` subclass + unless a custom message factory was specified when the :class:`Mailbox` + instance was initialized. -.. method:: Mailbox.itervalues() - Mailbox.__iter__() - Mailbox.values() + .. note:: - Return an iterator over representations of all messages if called as - :meth:`itervalues` or :meth:`__iter__` or return a list of such representations - if called as :meth:`values`. The messages are represented as instances of the - appropriate format-specific :class:`Message` subclass unless a custom message - factory was specified when the :class:`Mailbox` instance was initialized. + The behavior of :meth:`__iter__` is unlike that of dictionaries, which + iterate over keys. - .. note:: - The behavior of :meth:`__iter__` is unlike that of dictionaries, which iterate - over keys. + .. method:: iteritems() + items() + Return an iterator over (*key*, *message*) pairs, where *key* is a key and + *message* is a message representation, if called as :meth:`iteritems` or + return a list of such pairs if called as :meth:`items`. The messages are + represented as instances of the appropriate format-specific + :class:`Message` subclass unless a custom message factory was specified + when the :class:`Mailbox` instance was initialized. -.. method:: Mailbox.iteritems() - Mailbox.items() - Return an iterator over (*key*, *message*) pairs, where *key* is a key and - *message* is a message representation, if called as :meth:`iteritems` or return - a list of such pairs if called as :meth:`items`. The messages are represented as - instances of the appropriate format-specific :class:`Message` subclass unless a - custom message factory was specified when the :class:`Mailbox` instance was - initialized. + .. method:: 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 + :meth:`get` and a :exc:`KeyError` exception is raised if the method was + called as :meth:`__getitem__`. The message is represented as an instance + of the appropriate format-specific :class:`Message` subclass unless a + custom message factory was specified when the :class:`Mailbox` instance + was initialized. -.. method:: Mailbox.get(key[, default=None]) - Mailbox.__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 :meth:`get` - and a :exc:`KeyError` exception is raised if the method was called as - :meth:`__getitem__`. The message is represented as an instance of the - appropriate format-specific :class:`Message` subclass unless a custom message - factory was specified when the :class:`Mailbox` instance was initialized. + .. method:: get_message(key) + Return a representation of the message corresponding to *key* as an + instance of the appropriate format-specific :class:`Message` subclass, or + raise a :exc:`KeyError` exception if no such message exists. -.. method:: Mailbox.get_message(key) - Return a representation of the message corresponding to *key* as an instance of - the appropriate format-specific :class:`Message` subclass, or raise a - :exc:`KeyError` exception if no such message exists. + .. method:: get_string(key) + Return a string representation of the message corresponding to *key*, or + raise a :exc:`KeyError` exception if no such message exists. -.. method:: Mailbox.get_string(key) - Return a string representation of the message corresponding to *key*, or raise a - :exc:`KeyError` exception if no such message exists. + .. method:: get_file(key) + Return a file-like representation of the message corresponding to *key*, + or raise a :exc:`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. -.. method:: Mailbox.get_file(key) + .. note:: - Return a file-like representation of the message corresponding to *key*, or - raise a :exc:`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. + Unlike other representations of messages, file-like representations are + not necessarily independent of the :class:`Mailbox` instance that + created them or of the underlying mailbox. More specific documentation + is provided by each subclass. - .. note:: - Unlike other representations of messages, file-like representations are not - necessarily independent of the :class:`Mailbox` instance that created them or of - the underlying mailbox. More specific documentation is provided by each - subclass. + .. method:: has_key(key) + __contains__(key) + Return ``True`` if *key* corresponds to a message, ``False`` otherwise. -.. method:: Mailbox.has_key(key) - Mailbox.__contains__(key) - Return ``True`` if *key* corresponds to a message, ``False`` otherwise. + .. method:: __len__() + Return a count of messages in the mailbox. -.. method:: Mailbox.__len__() - Return a count of messages in the mailbox. + .. method:: clear() + Delete all messages from the mailbox. -.. method:: Mailbox.clear() - Delete all messages from the mailbox. + .. method:: 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 :exc:`KeyError` exception. The message is + represented as an instance of the appropriate format-specific + :class:`Message` subclass unless a custom message factory was specified + when the :class:`Mailbox` instance was initialized. -.. method:: 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 :exc:`KeyError` exception. The message is represented as an instance of - the appropriate format-specific :class:`Message` subclass unless a custom - message factory was specified when the :class:`Mailbox` instance was - initialized. + .. method:: 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 :exc:`KeyError` exception. The + message is represented as an instance of the appropriate format-specific + :class:`Message` subclass unless a custom message factory was specified + when the :class:`Mailbox` instance was initialized. -.. method:: Mailbox.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 :exc:`KeyError` exception. The message is represented - as an instance of the appropriate format-specific :class:`Message` subclass - unless a custom message factory was specified when the :class:`Mailbox` instance - was initialized. + .. method:: 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 :meth:`__setitem__`. As with :meth:`__setitem__`, + each *key* must already correspond to a message in the mailbox or else a + :exc:`KeyError` exception will be raised, so in general it is incorrect + for *arg* to be a :class:`Mailbox` instance. -.. method:: Mailbox.update(arg) + .. note:: - 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 - :meth:`__setitem__`. As with :meth:`__setitem__`, each *key* must already - correspond to a message in the mailbox or else a :exc:`KeyError` exception will - be raised, so in general it is incorrect for *arg* to be a :class:`Mailbox` - instance. + Unlike with dictionaries, keyword arguments are not supported. - .. note:: - Unlike with dictionaries, keyword arguments are not supported. + .. method:: flush() + Write any pending changes to the filesystem. For some :class:`Mailbox` + subclasses, changes are always written immediately and :meth:`flush` does + nothing, but you should still make a habit of calling this method. -.. method:: Mailbox.flush() - Write any pending changes to the filesystem. For some :class:`Mailbox` - subclasses, changes are always written immediately and :meth:`flush` does - nothing, but you should still make a habit of calling this method. + .. method:: lock() + Acquire an exclusive advisory lock on the mailbox so that other processes + know not to modify it. An :exc:`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. -.. method:: Mailbox.lock() - Acquire an exclusive advisory lock on the mailbox so that other processes know - not to modify it. An :exc:`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. + .. method:: unlock() + Release the lock on the mailbox, if any. -.. method:: Mailbox.unlock() - Release the lock on the mailbox, if any. + .. method:: close() - -.. method:: Mailbox.close() - - Flush the mailbox, unlock it if necessary, and close any open files. For some - :class:`Mailbox` subclasses, this method does nothing. + Flush the mailbox, unlock it if necessary, and close any open files. For + some :class:`Mailbox` subclasses, this method does nothing. .. _mailbox-maildir: @@ -286,113 +292,115 @@ the corresponding message is subsequently removed. instance that behaves like instances of other :class:`Mailbox` subclasses, set *factory* to ``None``. -Maildir is a directory-based mailbox format invented for the qmail mail transfer -agent and now widely supported by other programs. Messages in a Maildir mailbox -are stored in separate files within a common directory structure. This design -allows Maildir mailboxes to be accessed and modified by multiple unrelated -programs without data corruption, so file locking is unnecessary. + Maildir is a directory-based mailbox format invented for the qmail mail + transfer agent and now widely supported by other programs. Messages in a + Maildir mailbox are stored in separate files within a common directory + structure. This design allows Maildir mailboxes to be accessed and modified + by multiple unrelated programs without data corruption, so file locking is + unnecessary. + + Maildir mailboxes contain three subdirectories, namely: :file:`tmp`, + :file:`new`, and :file:`cur`. Messages are created momentarily in the + :file:`tmp` subdirectory and then moved to the :file:`new` subdirectory to + finalize delivery. A mail user agent may subsequently move the message to the + :file:`cur` subdirectory and store information about the state of the message + in a special "info" section appended to its file name. + + Folders of the style introduced by the Courier mail transfer agent are also + supported. Any subdirectory of the main mailbox is considered a folder if + ``'.'`` is the first character in its name. Folder names are represented by + :class:`Maildir` without the leading ``'.'``. Each folder is itself a Maildir + mailbox but should not contain other folders. Instead, a logical nesting is + indicated using ``'.'`` to delimit levels, e.g., "Archived.2005.07". -Maildir mailboxes contain three subdirectories, namely: :file:`tmp`, -:file:`new`, and :file:`cur`. Messages are created momentarily in the -:file:`tmp` subdirectory and then moved to the :file:`new` subdirectory to -finalize delivery. A mail user agent may subsequently move the message to the -:file:`cur` subdirectory and store information about the state of the message in -a special "info" section appended to its file name. + .. note:: -Folders of the style introduced by the Courier mail transfer agent are also -supported. Any subdirectory of the main mailbox is considered a folder if -``'.'`` is the first character in its name. Folder names are represented by -:class:`Maildir` without the leading ``'.'``. Each folder is itself a Maildir -mailbox but should not contain other folders. Instead, a logical nesting is -indicated using ``'.'`` to delimit levels, e.g., "Archived.2005.07". + The Maildir specification requires the use of a colon (``':'``) in certain + message file names. However, some operating systems do not permit this + character in file names, If you wish to use a Maildir-like format on such + an operating system, you should specify another character to use + instead. The exclamation point (``'!'``) is a popular choice. For + example:: -.. note:: + import mailbox + mailbox.Maildir.colon = '!' - The Maildir specification requires the use of a colon (``':'``) in certain - message file names. However, some operating systems do not permit this character - in file names, If you wish to use a Maildir-like format on such an operating - system, you should specify another character to use instead. The exclamation - point (``'!'``) is a popular choice. For example:: + The :attr:`colon` attribute may also be set on a per-instance basis. - import mailbox - mailbox.Maildir.colon = '!' + :class:`Maildir` instances have all of the methods of :class:`Mailbox` in + addition to the following: - The :attr:`colon` attribute may also be set on a per-instance basis. -:class:`Maildir` instances have all of the methods of :class:`Mailbox` in -addition to the following: + .. method:: list_folders() + Return a list of the names of all folders. -.. method:: Maildir.list_folders() - Return a list of the names of all folders. + .. method:: .et_folder(folder) + Return a :class:`Maildir` instance representing the folder whose name is + *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder + does not exist. -.. method:: Maildir.get_folder(folder) - Return a :class:`Maildir` instance representing the folder whose name is - *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder does not - exist. + .. method:: add_folder(folder) + Create a folder whose name is *folder* and return a :class:`Maildir` + instance representing it. -.. method:: Maildir.add_folder(folder) - Create a folder whose name is *folder* and return a :class:`Maildir` instance - representing it. + .. method:: remove_folder(folder) + Delete the folder whose name is *folder*. If the folder contains any + messages, a :exc:`NotEmptyError` exception will be raised and the folder + will not be deleted. -.. method:: Maildir.remove_folder(folder) - Delete the folder whose name is *folder*. If the folder contains any messages, a - :exc:`NotEmptyError` exception will be raised and the folder will not be - deleted. + .. method:: clean() + Delete temporary files from the mailbox that have not been accessed in the + last 36 hours. The Maildir specification says that mail-reading programs + should do this occasionally. -.. method:: Maildir.clean() + Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special + remarks: - Delete temporary files from the mailbox that have not been accessed in the last - 36 hours. The Maildir specification says that mail-reading programs should do - this occasionally. -Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special -remarks: + .. method:: add(message) + __setitem__(key, message) + update(arg) + .. warning:: -.. method:: Maildir.add(message) - Maildir.__setitem__(key, message) - Maildir.update(arg) + These methods generate unique file names based upon the current process + ID. When using multiple threads, undetected name clashes may occur and + cause corruption of the mailbox unless threads are coordinated to avoid + using these methods to manipulate the same mailbox simultaneously. - .. warning:: - These methods generate unique file names based upon the current process ID. When - using multiple threads, undetected name clashes may occur and cause corruption - of the mailbox unless threads are coordinated to avoid using these methods to - manipulate the same mailbox simultaneously. + .. method:: flush() + All changes to Maildir mailboxes are immediately applied, so this method + does nothing. -.. method:: Maildir.flush() - All changes to Maildir mailboxes are immediately applied, so this method does - nothing. + .. method:: lock() + unlock() + Maildir mailboxes do not support (or require) locking, so these methods do + nothing. -.. method:: Maildir.lock() - Maildir.unlock() - Maildir mailboxes do not support (or require) locking, so these methods do - nothing. + .. method:: close() + :class:`Maildir` instances do not keep any open files and the underlying + mailboxes do not support locking, so this method does nothing. -.. method:: Maildir.close() - :class:`Maildir` instances do not keep any open files and the underlying - mailboxes do not support locking, so this method does nothing. + .. method:: get_file(key) - -.. method:: Maildir.get_file(key) - - Depending upon the host platform, it may not be possible to modify or remove the - underlying message while the returned file remains open. + Depending upon the host platform, it may not be possible to modify or + remove the underlying message while the returned file remains open. .. seealso:: @@ -424,33 +432,34 @@ remarks: representation. If *create* is ``True``, the mailbox is created if it does not exist. -The mbox format is the classic format for storing mail on Unix systems. All -messages in an mbox mailbox are stored in a single file with the beginning of -each message indicated by a line whose first five characters are "From ". + The mbox format is the classic format for storing mail on Unix systems. All + messages in an mbox mailbox are stored in a single file with the beginning of + each message indicated by a line whose first five characters are "From ". -Several variations of the mbox format exist to address perceived shortcomings in -the original. In the interest of compatibility, :class:`mbox` implements the -original format, which is sometimes referred to as :dfn:`mboxo`. This means that -the :mailheader:`Content-Length` header, if present, is ignored and that any -occurrences of "From " at the beginning of a line in a message body are -transformed to ">From " when storing the message, although occurrences of ">From -" are not transformed to "From " when reading the message. + Several variations of the mbox format exist to address perceived shortcomings in + the original. In the interest of compatibility, :class:`mbox` implements the + original format, which is sometimes referred to as :dfn:`mboxo`. This means that + the :mailheader:`Content-Length` header, if present, is ignored and that any + occurrences of "From " at the beginning of a line in a message body are + transformed to ">From " when storing the message, although occurrences of ">From + " are not transformed to "From " when reading the message. -Some :class:`Mailbox` methods implemented by :class:`mbox` deserve special -remarks: + Some :class:`Mailbox` methods implemented by :class:`mbox` deserve special + remarks: -.. method:: mbox.get_file(key) + .. method:: get_file(key) - Using the file after calling :meth:`flush` or :meth:`close` on the :class:`mbox` - instance may yield unpredictable results or raise an exception. + Using the file after calling :meth:`flush` or :meth:`close` on the + :class:`mbox` instance may yield unpredictable results or raise an + exception. -.. method:: mbox.lock() - mbox.unlock() + .. method:: lock() + unlock() - Three locking mechanisms are used---dot locking and, if available, the - :cfunc:`flock` and :cfunc:`lockf` system calls. + Three locking mechanisms are used---dot locking and, if available, the + :cfunc:`flock` and :cfunc:`lockf` system calls. .. seealso:: @@ -483,106 +492,109 @@ remarks: representation. If *create* is ``True``, the mailbox is created if it does not exist. -MH is a directory-based mailbox format invented for the MH Message Handling -System, a mail user agent. Each message in an MH mailbox resides in its own -file. An MH mailbox may contain other MH mailboxes (called :dfn:`folders`) in -addition to messages. Folders may be nested indefinitely. MH mailboxes also -support :dfn:`sequences`, which are named lists used to logically group messages -without moving them to sub-folders. Sequences are defined in a file called -:file:`.mh_sequences` in each folder. + MH is a directory-based mailbox format invented for the MH Message Handling + System, a mail user agent. Each message in an MH mailbox resides in its own + file. An MH mailbox may contain other MH mailboxes (called :dfn:`folders`) in + addition to messages. Folders may be nested indefinitely. MH mailboxes also + support :dfn:`sequences`, which are named lists used to logically group + messages without moving them to sub-folders. Sequences are defined in a file + called :file:`.mh_sequences` in each folder. -The :class:`MH` class manipulates MH mailboxes, but it does not attempt to -emulate all of :program:`mh`'s behaviors. In particular, it does not modify and -is not affected by the :file:`context` or :file:`.mh_profile` files that are -used by :program:`mh` to store its state and configuration. + The :class:`MH` class manipulates MH mailboxes, but it does not attempt to + emulate all of :program:`mh`'s behaviors. In particular, it does not modify + and is not affected by the :file:`context` or :file:`.mh_profile` files that + are used by :program:`mh` to store its state and configuration. -:class:`MH` instances have all of the methods of :class:`Mailbox` in addition to -the following: + :class:`MH` instances have all of the methods of :class:`Mailbox` in addition + to the following: -.. method:: MH.list_folders() + .. method:: list_folders() - Return a list of the names of all folders. + Return a list of the names of all folders. -.. method:: MH.get_folder(folder) + .. method:: get_folder(folder) - Return an :class:`MH` instance representing the folder whose name is *folder*. A - :exc:`NoSuchMailboxError` exception is raised if the folder does not exist. + Return an :class:`MH` instance representing the folder whose name is + *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder + does not exist. -.. method:: MH.add_folder(folder) + .. method:: add_folder(folder) - Create a folder whose name is *folder* and return an :class:`MH` instance - representing it. + Create a folder whose name is *folder* and return an :class:`MH` instance + representing it. -.. method:: MH.remove_folder(folder) + .. method:: remove_folder(folder) - Delete the folder whose name is *folder*. If the folder contains any messages, a - :exc:`NotEmptyError` exception will be raised and the folder will not be - deleted. + Delete the folder whose name is *folder*. If the folder contains any + messages, a :exc:`NotEmptyError` exception will be raised and the folder + will not be deleted. -.. method:: MH.get_sequences() + .. method:: get_sequences() - Return a dictionary of sequence names mapped to key lists. If there are no - sequences, the empty dictionary is returned. + Return a dictionary of sequence names mapped to key lists. If there are no + sequences, the empty dictionary is returned. -.. method:: MH.set_sequences(sequences) + .. method:: set_sequences(sequences) - Re-define the sequences that exist in the mailbox based upon *sequences*, a - dictionary of names mapped to key lists, like returned by :meth:`get_sequences`. + Re-define the sequences that exist in the mailbox based upon *sequences*, + a dictionary of names mapped to key lists, like returned by + :meth:`get_sequences`. -.. method:: MH.pack() + .. method:: pack() - Rename messages in the mailbox as necessary to eliminate gaps in numbering. - Entries in the sequences list are updated correspondingly. + Rename messages in the mailbox as necessary to eliminate gaps in + numbering. Entries in the sequences list are updated correspondingly. - .. note:: + .. note:: - Already-issued keys are invalidated by this operation and should not be - subsequently used. + Already-issued keys are invalidated by this operation and should not be + subsequently used. -Some :class:`Mailbox` methods implemented by :class:`MH` deserve special -remarks: + Some :class:`Mailbox` methods implemented by :class:`MH` deserve special + remarks: -.. method:: MH.remove(key) - MH.__delitem__(key) - MH.discard(key) + .. method:: remove(key) + __delitem__(key) + discard(key) - These methods immediately delete the message. The MH convention of marking a - message for deletion by prepending a comma to its name is not used. + These methods immediately delete the message. The MH convention of marking + a message for deletion by prepending a comma to its name is not used. -.. method:: MH.lock() - MH.unlock() + .. method:: lock() + unlock() - Three locking mechanisms are used---dot locking and, if available, the - :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking the - mailbox means locking the :file:`.mh_sequences` file and, only for the duration - of any operations that affect them, locking individual message files. + Three locking mechanisms are used---dot locking and, if available, the + :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking + the mailbox means locking the :file:`.mh_sequences` file and, only for the + duration of any operations that affect them, locking individual message + files. -.. method:: MH.get_file(key) + .. method:: get_file(key) - Depending upon the host platform, it may not be possible to remove the - underlying message while the returned file remains open. + Depending upon the host platform, it may not be possible to remove the + underlying message while the returned file remains open. -.. method:: MH.flush() + .. method:: flush() - All changes to MH mailboxes are immediately applied, so this method does - nothing. + All changes to MH mailboxes are immediately applied, so this method does + nothing. -.. method:: MH.close() + .. method:: close() - :class:`MH` instances do not keep any open files, so this method is equivalent - to :meth:`unlock`. + :class:`MH` instances do not keep any open files, so this method is + equivalent to :meth:`unlock`. .. seealso:: @@ -610,54 +622,56 @@ remarks: representation. If *create* is ``True``, the mailbox is created if it does not exist. -Babyl is a single-file mailbox format used by the Rmail mail user agent included -with Emacs. The beginning of a message is indicated by a line containing the two -characters Control-Underscore (``'\037'``) and Control-L (``'\014'``). The end -of a message is indicated by the start of the next message or, in the case of -the last message, a line containing a Control-Underscore (``'\037'``) -character. + Babyl is a single-file mailbox format used by the Rmail mail user agent + included with Emacs. The beginning of a message is indicated by a line + containing the two characters Control-Underscore (``'\037'``) and Control-L + (``'\014'``). The end of a message is indicated by the start of the next + message or, in the case of the last message, a line containing a + Control-Underscore (``'\037'``) character. -Messages in a Babyl mailbox have two sets of headers, original headers and -so-called visible headers. Visible headers are typically a subset of the -original headers that have been reformatted or abridged to be more -attractive. Each message in a Babyl mailbox also has an accompanying list of -:dfn:`labels`, or short strings that record extra information about the message, -and a list of all user-defined labels found in the mailbox is kept in the Babyl -options section. + Messages in a Babyl mailbox have two sets of headers, original headers and + so-called visible headers. Visible headers are typically a subset of the + original headers that have been reformatted or abridged to be more + attractive. Each message in a Babyl mailbox also has an accompanying list of + :dfn:`labels`, or short strings that record extra information about the + message, and a list of all user-defined labels found in the mailbox is kept + in the Babyl options section. -:class:`Babyl` instances have all of the methods of :class:`Mailbox` in addition -to the following: + :class:`Babyl` instances have all of the methods of :class:`Mailbox` in + addition to the following: -.. method:: Babyl.get_labels() + .. method:: get_labels() - Return a list of the names of all user-defined labels used in the mailbox. + Return a list of the names of all user-defined labels used in the mailbox. - .. note:: + .. note:: - The actual messages are inspected to determine which labels exist in the mailbox - rather than consulting the list of labels in the Babyl options section, but the - Babyl section is updated whenever the mailbox is modified. + The actual messages are inspected to determine which labels exist in + the mailbox rather than consulting the list of labels in the Babyl + options section, but the Babyl section is updated whenever the mailbox + is modified. -Some :class:`Mailbox` methods implemented by :class:`Babyl` deserve special -remarks: + Some :class:`Mailbox` methods implemented by :class:`Babyl` deserve special + remarks: -.. method:: Babyl.get_file(key) + .. method:: get_file(key) - In Babyl mailboxes, the headers of a message are not stored contiguously with - the body of the message. To generate a file-like representation, the headers and - body are copied together into a :class:`StringIO` instance (from the - :mod:`StringIO` module), which has an API identical to that of a file. As a - result, the file-like object is truly independent of the underlying mailbox but - does not save memory compared to a string representation. + In Babyl mailboxes, the headers of a message are not stored contiguously + with the body of the message. To generate a file-like representation, the + headers and body are copied together into a :class:`StringIO` instance + (from the :mod:`StringIO` module), which has an API identical to that of a + file. As a result, the file-like object is truly independent of the + underlying mailbox but does not save memory compared to a string + representation. -.. method:: Babyl.lock() - Babyl.unlock() + .. method:: lock() + unlock() - Three locking mechanisms are used---dot locking and, if available, the - :cfunc:`flock` and :cfunc:`lockf` system calls. + Three locking mechanisms are used---dot locking and, if available, the + :cfunc:`flock` and :cfunc:`lockf` system calls. .. seealso:: @@ -684,30 +698,31 @@ remarks: representation. If *create* is ``True``, the mailbox is created if it does not exist. -MMDF is a single-file mailbox format invented for the Multichannel Memorandum -Distribution Facility, a mail transfer agent. Each message is in the same form -as an mbox message but is bracketed before and after by lines containing four -Control-A (``'\001'``) characters. As with the mbox format, the beginning of -each message is indicated by a line whose first five characters are "From ", but -additional occurrences of "From " are not transformed to ">From " when storing -messages because the extra message separator lines prevent mistaking such -occurrences for the starts of subsequent messages. + MMDF is a single-file mailbox format invented for the Multichannel Memorandum + Distribution Facility, a mail transfer agent. Each message is in the same + form as an mbox message but is bracketed before and after by lines containing + four Control-A (``'\001'``) characters. As with the mbox format, the + beginning of each message is indicated by a line whose first five characters + are "From ", but additional occurrences of "From " are not transformed to + ">From " when storing messages because the extra message separator lines + prevent mistaking such occurrences for the starts of subsequent messages. -Some :class:`Mailbox` methods implemented by :class:`MMDF` deserve special -remarks: + Some :class:`Mailbox` methods implemented by :class:`MMDF` deserve special + remarks: -.. method:: MMDF.get_file(key) + .. method:: get_file(key) - Using the file after calling :meth:`flush` or :meth:`close` on the :class:`MMDF` - instance may yield unpredictable results or raise an exception. + Using the file after calling :meth:`flush` or :meth:`close` on the + :class:`MMDF` instance may yield unpredictable results or raise an + exception. -.. method:: MMDF.lock() - MMDF.unlock() + .. method:: lock() + unlock() - Three locking mechanisms are used---dot locking and, if available, the - :cfunc:`flock` and :cfunc:`lockf` system calls. + Three locking mechanisms are used---dot locking and, if available, the + :cfunc:`flock` and :cfunc:`lockf` system calls. .. seealso:: @@ -738,21 +753,21 @@ remarks: or a file, it should contain an :rfc:`2822`\ -compliant message, which is read and parsed. -The format-specific state and behaviors offered by subclasses vary, but in -general it is only the properties that are not specific to a particular mailbox -that are supported (although presumably the properties are specific to a -particular mailbox format). For example, file offsets for single-file mailbox -formats and file names for directory-based mailbox formats are not retained, -because they are only applicable to the original mailbox. But state such as -whether a message has been read by the user or marked as important is retained, -because it applies to the message itself. + The format-specific state and behaviors offered by subclasses vary, but in + general it is only the properties that are not specific to a particular + mailbox that are supported (although presumably the properties are specific + to a particular mailbox format). For example, file offsets for single-file + mailbox formats and file names for directory-based mailbox formats are not + retained, because they are only applicable to the original mailbox. But state + such as whether a message has been read by the user or marked as important is + retained, because it applies to the message itself. -There is no requirement that :class:`Message` instances be used to represent -messages retrieved using :class:`Mailbox` instances. In some situations, the -time and memory required to generate :class:`Message` representations might not -not acceptable. For such situations, :class:`Mailbox` instances also offer -string and file-like representations, and a custom message factory may be -specified when a :class:`Mailbox` instance is initialized. + There is no requirement that :class:`Message` instances be used to represent + messages retrieved using :class:`Mailbox` instances. In some situations, the + time and memory required to generate :class:`Message` representations might + not not acceptable. For such situations, :class:`Mailbox` instances also + offer string and file-like representations, and a custom message factory may + be specified when a :class:`Mailbox` instance is initialized. .. _mailbox-maildirmessage: @@ -766,106 +781,109 @@ specified when a :class:`Mailbox` instance is initialized. A message with Maildir-specific behaviors. Parameter *message* has the same meaning as with the :class:`Message` constructor. -Typically, a mail user agent application moves all of the messages in the -:file:`new` subdirectory to the :file:`cur` subdirectory after the first time -the user opens and closes the mailbox, recording that the messages are old -whether or not they've actually been read. Each message in :file:`cur` has an -"info" section added to its file name to store information about its state. -(Some mail readers may also add an "info" section to messages in :file:`new`.) -The "info" section may take one of two forms: it may contain "2," followed by a -list of standardized flags (e.g., "2,FR") or it may contain "1," followed by -so-called experimental information. Standard flags for Maildir messages are as -follows: - -+------+---------+--------------------------------+ -| Flag | Meaning | Explanation | -+======+=========+================================+ -| D | Draft | Under composition | -+------+---------+--------------------------------+ -| F | Flagged | Marked as important | -+------+---------+--------------------------------+ -| P | Passed | Forwarded, resent, or bounced | -+------+---------+--------------------------------+ -| R | Replied | Replied to | -+------+---------+--------------------------------+ -| S | Seen | Read | -+------+---------+--------------------------------+ -| T | Trashed | Marked for subsequent deletion | -+------+---------+--------------------------------+ - -:class:`MaildirMessage` instances offer the following methods: - - -.. method:: MaildirMessage.get_subdir() - - Return either "new" (if the message should be stored in the :file:`new` - subdirectory) or "cur" (if the message should be stored in the :file:`cur` - subdirectory). + Typically, a mail user agent application moves all of the messages in the + :file:`new` subdirectory to the :file:`cur` subdirectory after the first time + the user opens and closes the mailbox, recording that the messages are old + whether or not they've actually been read. Each message in :file:`cur` has an + "info" section added to its file name to store information about its state. + (Some mail readers may also add an "info" section to messages in + :file:`new`.) The "info" section may take one of two forms: it may contain + "2," followed by a list of standardized flags (e.g., "2,FR") or it may + contain "1," followed by so-called experimental information. Standard flags + for Maildir messages are as follows: - .. note:: + +------+---------+--------------------------------+ + | Flag | Meaning | Explanation | + +======+=========+================================+ + | D | Draft | Under composition | + +------+---------+--------------------------------+ + | F | Flagged | Marked as important | + +------+---------+--------------------------------+ + | P | Passed | Forwarded, resent, or bounced | + +------+---------+--------------------------------+ + | R | Replied | Replied to | + +------+---------+--------------------------------+ + | S | Seen | Read | + +------+---------+--------------------------------+ + | T | Trashed | Marked for subsequent deletion | + +------+---------+--------------------------------+ + + :class:`MaildirMessage` instances offer the following methods: + + + .. method:: get_subdir() + + Return either "new" (if the message should be stored in the :file:`new` + subdirectory) or "cur" (if the message should be stored in the :file:`cur` + subdirectory). + + .. note:: - A message is typically moved from :file:`new` to :file:`cur` after its mailbox - has been accessed, whether or not the message is has been read. A message - ``msg`` has been read if ``"S" in msg.get_flags()`` is ``True``. + A message is typically moved from :file:`new` to :file:`cur` after its + mailbox has been accessed, whether or not the message is has been + read. A message ``msg`` has been read if ``"S" in msg.get_flags()`` is + ``True``. -.. method:: MaildirMessage.set_subdir(subdir) + .. method:: set_subdir(subdir) - Set the subdirectory the message should be stored in. Parameter *subdir* must be - either "new" or "cur". + Set the subdirectory the message should be stored in. Parameter *subdir* + must be either "new" or "cur". -.. method:: MaildirMessage.get_flags() + .. method:: get_flags() - Return a string specifying the flags that are currently set. If the message - complies with the standard Maildir format, the result is the concatenation in - alphabetical order of zero or one occurrence of each of ``'D'``, ``'F'``, - ``'P'``, ``'R'``, ``'S'``, and ``'T'``. The empty string is returned if no flags - are set or if "info" contains experimental semantics. + Return a string specifying the flags that are currently set. If the + message complies with the standard Maildir format, the result is the + concatenation in alphabetical order of zero or one occurrence of each of + ``'D'``, ``'F'``, ``'P'``, ``'R'``, ``'S'``, and ``'T'``. The empty string + is returned if no flags are set or if "info" contains experimental + semantics. -.. method:: MaildirMessage.set_flags(flags) + .. method:: set_flags(flags) - Set the flags specified by *flags* and unset all others. + Set the flags specified by *flags* and unset all others. -.. method:: MaildirMessage.add_flag(flag) + .. method:: add_flag(flag) - Set the flag(s) specified by *flag* without changing other flags. To add more - than one flag at a time, *flag* may be a string of more than one character. The - current "info" is overwritten whether or not it contains experimental - information rather than flags. + Set the flag(s) specified by *flag* without changing other flags. To add + more than one flag at a time, *flag* may be a string of more than one + character. The current "info" is overwritten whether or not it contains + experimental information rather than flags. -.. method:: MaildirMessage.remove_flag(flag) + .. method:: remove_flag(flag) - Unset the flag(s) specified by *flag* without changing other flags. To remove - more than one flag at a time, *flag* maybe a string of more than one character. - If "info" contains experimental information rather than flags, the current - "info" is not modified. + Unset the flag(s) specified by *flag* without changing other flags. To + remove more than one flag at a time, *flag* maybe a string of more than + one character. If "info" contains experimental information rather than + flags, the current "info" is not modified. -.. method:: MaildirMessage.get_date() + .. method:: get_date() - Return the delivery date of the message as a floating-point number representing - seconds since the epoch. + Return the delivery date of the message as a floating-point number + representing seconds since the epoch. -.. method:: MaildirMessage.set_date(date) + .. method:: set_date(date) - Set the delivery date of the message to *date*, a floating-point number - representing seconds since the epoch. + Set the delivery date of the message to *date*, a floating-point number + representing seconds since the epoch. -.. method:: MaildirMessage.get_info() + .. method:: get_info() - Return a string containing the "info" for a message. This is useful for - accessing and modifying "info" that is experimental (i.e., not a list of flags). + Return a string containing the "info" for a message. This is useful for + accessing and modifying "info" that is experimental (i.e., not a list of + flags). -.. method:: MaildirMessage.set_info(info) + .. method:: set_info(info) - Set "info" to *info*, which should be a string. + Set "info" to *info*, which should be a string. When a :class:`MaildirMessage` instance is created based upon an :class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status` @@ -931,78 +949,81 @@ When a :class:`MaildirMessage` instance is created based upon a A message with mbox-specific behaviors. Parameter *message* has the same meaning as with the :class:`Message` constructor. -Messages in an mbox mailbox are stored together in a single file. The sender's -envelope address and the time of delivery are typically stored in a line -beginning with "From " that is used to indicate the start of a message, though -there is considerable variation in the exact format of this data among mbox -implementations. Flags that indicate the state of the message, such as whether -it has been read or marked as important, are typically stored in -:mailheader:`Status` and :mailheader:`X-Status` headers. + Messages in an mbox mailbox are stored together in a single file. The + sender's envelope address and the time of delivery are typically stored in a + line beginning with "From " that is used to indicate the start of a message, + though there is considerable variation in the exact format of this data among + mbox implementations. Flags that indicate the state of the message, such as + whether it has been read or marked as important, are typically stored in + :mailheader:`Status` and :mailheader:`X-Status` headers. -Conventional flags for mbox messages are as follows: + Conventional flags for mbox messages are as follows: -+------+----------+--------------------------------+ -| Flag | Meaning | Explanation | -+======+==========+================================+ -| R | Read | Read | -+------+----------+--------------------------------+ -| O | Old | Previously detected by MUA | -+------+----------+--------------------------------+ -| D | Deleted | Marked for subsequent deletion | -+------+----------+--------------------------------+ -| F | Flagged | Marked as important | -+------+----------+--------------------------------+ -| A | Answered | Replied to | -+------+----------+--------------------------------+ + +------+----------+--------------------------------+ + | Flag | Meaning | Explanation | + +======+==========+================================+ + | R | Read | Read | + +------+----------+--------------------------------+ + | O | Old | Previously detected by MUA | + +------+----------+--------------------------------+ + | D | Deleted | Marked for subsequent deletion | + +------+----------+--------------------------------+ + | F | Flagged | Marked as important | + +------+----------+--------------------------------+ + | A | Answered | Replied to | + +------+----------+--------------------------------+ -The "R" and "O" flags are stored in the :mailheader:`Status` header, and the -"D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The -flags and headers typically appear in the order mentioned. + The "R" and "O" flags are stored in the :mailheader:`Status` header, and the + "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The + flags and headers typically appear in the order mentioned. -:class:`mboxMessage` instances offer the following methods: + :class:`mboxMessage` instances offer the following methods: -.. method:: mboxMessage.get_from() + .. method:: get_from() - Return a string representing the "From " line that marks the start of the - message in an mbox mailbox. The leading "From " and the trailing newline are - excluded. + Return a string representing the "From " line that marks the start of the + message in an mbox mailbox. The leading "From " and the trailing newline + are excluded. -.. method:: mboxMessage.set_from(from_[, time_=None]) + .. method:: set_from(from_[, time_=None]) - Set the "From " line to *from_*, which should be specified without a leading - "From " or trailing newline. For convenience, *time_* may be specified and will - be formatted appropriately and appended to *from_*. If *time_* is specified, it - should be a :class:`struct_time` instance, a tuple suitable for passing to - :meth:`time.strftime`, or ``True`` (to use :meth:`time.gmtime`). + Set the "From " line to *from_*, which should be specified without a + leading "From " or trailing newline. For convenience, *time_* may be + specified and will be formatted appropriately and appended to *from_*. If + *time_* is specified, it should be a :class:`struct_time` instance, a + tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use + :meth:`time.gmtime`). -.. method:: mboxMessage.get_flags() + .. method:: get_flags() - Return a string specifying the flags that are currently set. If the message - complies with the conventional format, the result is the concatenation in the - following order of zero or one occurrence of each of ``'R'``, ``'O'``, ``'D'``, - ``'F'``, and ``'A'``. + Return a string specifying the flags that are currently set. If the + message complies with the conventional format, the result is the + concatenation in the following order of zero or one occurrence of each of + ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``. -.. method:: mboxMessage.set_flags(flags) + .. method:: set_flags(flags) - Set the flags specified by *flags* and unset all others. Parameter *flags* - should be the concatenation in any order of zero or more occurrences of each of - ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``. + Set the flags specified by *flags* and unset all others. Parameter *flags* + should be the concatenation in any order of zero or more occurrences of + each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``. -.. method:: mboxMessage.add_flag(flag) + .. method:: add_flag(flag) - Set the flag(s) specified by *flag* without changing other flags. To add more - than one flag at a time, *flag* may be a string of more than one character. + Set the flag(s) specified by *flag* without changing other flags. To add + more than one flag at a time, *flag* may be a string of more than one + character. -.. method:: mboxMessage.remove_flag(flag) + .. method:: remove_flag(flag) - Unset the flag(s) specified by *flag* without changing other flags. To remove - more than one flag at a time, *flag* maybe a string of more than one character. + Unset the flag(s) specified by *flag* without changing other flags. To + remove more than one flag at a time, *flag* maybe a string of more than + one character. When an :class:`mboxMessage` instance is created based upon a :class:`MaildirMessage` instance, a "From " line is generated based upon the @@ -1082,43 +1103,43 @@ instance, the "From " line is copied and all flags directly correspond: A message with MH-specific behaviors. Parameter *message* has the same meaning as with the :class:`Message` constructor. -MH messages do not support marks or flags in the traditional sense, but they do -support sequences, which are logical groupings of arbitrary messages. Some mail -reading programs (although not the standard :program:`mh` and :program:`nmh`) -use sequences in much the same way flags are used with other formats, as -follows: + MH messages do not support marks or flags in the traditional sense, but they + do support sequences, which are logical groupings of arbitrary messages. Some + mail reading programs (although not the standard :program:`mh` and + :program:`nmh`) use sequences in much the same way flags are used with other + formats, as follows: -+----------+------------------------------------------+ -| Sequence | Explanation | -+==========+==========================================+ -| unseen | Not read, but previously detected by MUA | -+----------+------------------------------------------+ -| replied | Replied to | -+----------+------------------------------------------+ -| flagged | Marked as important | -+----------+------------------------------------------+ + +----------+------------------------------------------+ + | Sequence | Explanation | + +==========+==========================================+ + | unseen | Not read, but previously detected by MUA | + +----------+------------------------------------------+ + | replied | Replied to | + +----------+------------------------------------------+ + | flagged | Marked as important | + +----------+------------------------------------------+ -:class:`MHMessage` instances offer the following methods: + :class:`MHMessage` instances offer the following methods: -.. method:: MHMessage.get_sequences() + .. method:: get_sequences() - Return a list of the names of sequences that include this message. + Return a list of the names of sequences that include this message. -.. method:: MHMessage.set_sequences(sequences) + .. method:: set_sequences(sequences) - Set the list of sequences that include this message. + Set the list of sequences that include this message. -.. method:: MHMessage.add_sequence(sequence) + .. method:: add_sequence(sequence) - Add *sequence* to the list of sequences that include this message. + Add *sequence* to the list of sequences that include this message. -.. method:: MHMessage.remove_sequence(sequence) + .. method:: remove_sequence(sequence) - Remove *sequence* from the list of sequences that include this message. + Remove *sequence* from the list of sequences that include this message. When an :class:`MHMessage` instance is created based upon a :class:`MaildirMessage` instance, the following conversions take place: @@ -1172,79 +1193,79 @@ When an :class:`MHMessage` instance is created based upon a A message with Babyl-specific behaviors. Parameter *message* has the same meaning as with the :class:`Message` constructor. -Certain message labels, called :dfn:`attributes`, are defined by convention to -have special meanings. The attributes are as follows: + Certain message labels, called :dfn:`attributes`, are defined by convention + to have special meanings. The attributes are as follows: -+-----------+------------------------------------------+ -| Label | Explanation | -+===========+==========================================+ -| unseen | Not read, but previously detected by MUA | -+-----------+------------------------------------------+ -| deleted | Marked for subsequent deletion | -+-----------+------------------------------------------+ -| filed | Copied to another file or mailbox | -+-----------+------------------------------------------+ -| answered | Replied to | -+-----------+------------------------------------------+ -| forwarded | Forwarded | -+-----------+------------------------------------------+ -| edited | Modified by the user | -+-----------+------------------------------------------+ -| resent | Resent | -+-----------+------------------------------------------+ + +-----------+------------------------------------------+ + | Label | Explanation | + +===========+==========================================+ + | unseen | Not read, but previously detected by MUA | + +-----------+------------------------------------------+ + | deleted | Marked for subsequent deletion | + +-----------+------------------------------------------+ + | filed | Copied to another file or mailbox | + +-----------+------------------------------------------+ + | answered | Replied to | + +-----------+------------------------------------------+ + | forwarded | Forwarded | + +-----------+------------------------------------------+ + | edited | Modified by the user | + +-----------+------------------------------------------+ + | resent | Resent | + +-----------+------------------------------------------+ -By default, Rmail displays only visible headers. The :class:`BabylMessage` -class, though, uses the original headers because they are more complete. Visible -headers may be accessed explicitly if desired. + By default, Rmail displays only visible headers. The :class:`BabylMessage` + class, though, uses the original headers because they are more + complete. Visible headers may be accessed explicitly if desired. -:class:`BabylMessage` instances offer the following methods: + :class:`BabylMessage` instances offer the following methods: -.. method:: BabylMessage.get_labels() + .. method:: get_labels() - Return a list of labels on the message. + Return a list of labels on the message. -.. method:: BabylMessage.set_labels(labels) + .. method:: set_labels(labels) - Set the list of labels on the message to *labels*. + Set the list of labels on the message to *labels*. -.. method:: BabylMessage.add_label(label) + .. method:: add_label(label) - Add *label* to the list of labels on the message. + Add *label* to the list of labels on the message. -.. method:: BabylMessage.remove_label(label) + .. method:: remove_label(label) - Remove *label* from the list of labels on the message. + Remove *label* from the list of labels on the message. -.. method:: BabylMessage.get_visible() + .. method:: get_visible() - Return an :class:`Message` instance whose headers are the message's visible - headers and whose body is empty. + Return an :class:`Message` instance whose headers are the message's + visible headers and whose body is empty. -.. method:: BabylMessage.set_visible(visible) + .. method:: set_visible(visible) - Set the message's visible headers to be the same as the headers in *message*. - Parameter *visible* should be a :class:`Message` instance, an - :class:`email.Message.Message` instance, a string, or a file-like object (which - should be open in text mode). + Set the message's visible headers to be the same as the headers in + *message*. Parameter *visible* should be a :class:`Message` instance, an + :class:`email.Message.Message` instance, a string, or a file-like object + (which should be open in text mode). -.. method:: BabylMessage.update_visible() + .. method:: update_visible() - When a :class:`BabylMessage` instance's original headers are modified, the - visible headers are not automatically modified to correspond. This method - updates the visible headers as follows: each visible header with a corresponding - original header is set to the value of the original header, each visible header - without a corresponding original header is removed, and any of - :mailheader:`Date`, :mailheader:`From`, :mailheader:`Reply-To`, - :mailheader:`To`, :mailheader:`CC`, and :mailheader:`Subject` that are present - in the original headers but not the visible headers are added to the visible - headers. + When a :class:`BabylMessage` instance's original headers are modified, the + visible headers are not automatically modified to correspond. This method + updates the visible headers as follows: each visible header with a + corresponding original header is set to the value of the original header, + each visible header without a corresponding original header is removed, + and any of :mailheader:`Date`, :mailheader:`From`, :mailheader:`Reply-To`, + :mailheader:`To`, :mailheader:`CC`, and :mailheader:`Subject` that are + present in the original headers but not the visible headers are added to + the visible headers. When a :class:`BabylMessage` instance is created based upon a :class:`MaildirMessage` instance, the following conversions take place: @@ -1300,77 +1321,80 @@ When a :class:`BabylMessage` instance is created based upon an A message with MMDF-specific behaviors. Parameter *message* has the same meaning as with the :class:`Message` constructor. -As with message in an mbox mailbox, MMDF messages are stored with the sender's -address and the delivery date in an initial line beginning with "From ". -Likewise, flags that indicate the state of the message are typically stored in -:mailheader:`Status` and :mailheader:`X-Status` headers. + As with message in an mbox mailbox, MMDF messages are stored with the + sender's address and the delivery date in an initial line beginning with + "From ". Likewise, flags that indicate the state of the message are + typically stored in :mailheader:`Status` and :mailheader:`X-Status` headers. -Conventional flags for MMDF messages are identical to those of mbox message and -are as follows: + Conventional flags for MMDF messages are identical to those of mbox message + and are as follows: -+------+----------+--------------------------------+ -| Flag | Meaning | Explanation | -+======+==========+================================+ -| R | Read | Read | -+------+----------+--------------------------------+ -| O | Old | Previously detected by MUA | -+------+----------+--------------------------------+ -| D | Deleted | Marked for subsequent deletion | -+------+----------+--------------------------------+ -| F | Flagged | Marked as important | -+------+----------+--------------------------------+ -| A | Answered | Replied to | -+------+----------+--------------------------------+ + +------+----------+--------------------------------+ + | Flag | Meaning | Explanation | + +======+==========+================================+ + | R | Read | Read | + +------+----------+--------------------------------+ + | O | Old | Previously detected by MUA | + +------+----------+--------------------------------+ + | D | Deleted | Marked for subsequent deletion | + +------+----------+--------------------------------+ + | F | Flagged | Marked as important | + +------+----------+--------------------------------+ + | A | Answered | Replied to | + +------+----------+--------------------------------+ -The "R" and "O" flags are stored in the :mailheader:`Status` header, and the -"D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The -flags and headers typically appear in the order mentioned. + The "R" and "O" flags are stored in the :mailheader:`Status` header, and the + "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The + flags and headers typically appear in the order mentioned. -:class:`MMDFMessage` instances offer the following methods, which are identical -to those offered by :class:`mboxMessage`: + :class:`MMDFMessage` instances offer the following methods, which are + identical to those offered by :class:`mboxMessage`: -.. method:: MMDFMessage.get_from() + .. method:: get_from() - Return a string representing the "From " line that marks the start of the - message in an mbox mailbox. The leading "From " and the trailing newline are - excluded. + Return a string representing the "From " line that marks the start of the + message in an mbox mailbox. The leading "From " and the trailing newline + are excluded. -.. method:: MMDFMessage.set_from(from_[, time_=None]) + .. method:: set_from(from_[, time_=None]) - Set the "From " line to *from_*, which should be specified without a leading - "From " or trailing newline. For convenience, *time_* may be specified and will - be formatted appropriately and appended to *from_*. If *time_* is specified, it - should be a :class:`struct_time` instance, a tuple suitable for passing to - :meth:`time.strftime`, or ``True`` (to use :meth:`time.gmtime`). + Set the "From " line to *from_*, which should be specified without a + leading "From " or trailing newline. For convenience, *time_* may be + specified and will be formatted appropriately and appended to *from_*. If + *time_* is specified, it should be a :class:`struct_time` instance, a + tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use + :meth:`time.gmtime`). -.. method:: MMDFMessage.get_flags() + .. method:: get_flags() - Return a string specifying the flags that are currently set. If the message - complies with the conventional format, the result is the concatenation in the - following order of zero or one occurrence of each of ``'R'``, ``'O'``, ``'D'``, - ``'F'``, and ``'A'``. + Return a string specifying the flags that are currently set. If the + message complies with the conventional format, the result is the + concatenation in the following order of zero or one occurrence of each of + ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``. -.. method:: MMDFMessage.set_flags(flags) + .. method:: set_flags(flags) - Set the flags specified by *flags* and unset all others. Parameter *flags* - should be the concatenation in any order of zero or more occurrences of each of - ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``. + Set the flags specified by *flags* and unset all others. Parameter *flags* + should be the concatenation in any order of zero or more occurrences of + each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``. -.. method:: MMDFMessage.add_flag(flag) + .. method:: add_flag(flag) - Set the flag(s) specified by *flag* without changing other flags. To add more - than one flag at a time, *flag* may be a string of more than one character. + Set the flag(s) specified by *flag* without changing other flags. To add + more than one flag at a time, *flag* may be a string of more than one + character. -.. method:: MMDFMessage.remove_flag(flag) + .. method:: remove_flag(flag) - Unset the flag(s) specified by *flag* without changing other flags. To remove - more than one flag at a time, *flag* maybe a string of more than one character. + Unset the flag(s) specified by *flag* without changing other flags. To + remove more than one flag at a time, *flag* maybe a string of more than + one character. When an :class:`MMDFMessage` instance is created based upon a :class:`MaildirMessage` instance, a "From " line is generated based upon the @@ -1446,25 +1470,25 @@ Exceptions The following exception classes are defined in the :mod:`mailbox` module: -.. class:: Error() +.. exception:: Error() The based class for all other module-specific exceptions. -.. class:: NoSuchMailboxError() +.. exception:: NoSuchMailboxError() Raised when a mailbox is expected but is not found, such as when instantiating a :class:`Mailbox` subclass with a path that does not exist (and with the *create* parameter set to ``False``), or when opening a folder that does not exist. -.. class:: NotEmptyErrorError() +.. exception:: NotEmptyErrorError() Raised when a mailbox is not empty but is expected to be, such as when deleting a folder that contains messages. -.. class:: ExternalClashError() +.. exception:: ExternalClashError() Raised when some mailbox-related condition beyond the control of the program causes it to be unable to proceed, such as when failing to acquire a lock that @@ -1472,7 +1496,7 @@ The following exception classes are defined in the :mod:`mailbox` module: already exists. -.. class:: FormatError() +.. exception:: FormatError() Raised when the data in a file cannot be parsed, such as when an :class:`MH` instance attempts to read a corrupted :file:`.mh_sequences` file. |