diff options
Diffstat (limited to 'Doc/library/mailbox.rst')
| -rw-r--r-- | Doc/library/mailbox.rst | 127 |
1 files changed, 0 insertions, 127 deletions
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index f76c97a..6db68ee 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -1501,133 +1501,6 @@ The following exception classes are defined in the :mod:`mailbox` module: instance attempts to read a corrupted :file:`.mh_sequences` file. -.. _mailbox-deprecated: - -Deprecated classes and methods ------------------------------- - -Older versions of the :mod:`mailbox` module do not support modification of -mailboxes, such as adding or removing message, and do not provide classes to -represent format-specific message properties. For backward compatibility, the -older mailbox classes are still available, but the newer classes should be used -in preference to them. - -Older mailbox objects support only iteration and provide a single public method: - - -.. method:: oldmailbox.next() - - Return the next message in the mailbox, created with the optional *factory* - argument passed into the mailbox object's constructor. By default this is an - :class:`rfc822.Message` object (see the :mod:`rfc822` module). Depending on the - mailbox implementation the *fp* attribute of this object may be a true file - object or a class instance simulating a file object, taking care of things like - message boundaries if multiple mail messages are contained in a single file, - etc. If no more messages are available, this method returns ``None``. - -Most of the older mailbox classes have names that differ from the current -mailbox class names, except for :class:`Maildir`. For this reason, the new -:class:`Maildir` class defines a :meth:`next` method and its constructor differs -slightly from those of the other new mailbox classes. - -The older mailbox classes whose names are not the same as their newer -counterparts are as follows: - - -.. class:: UnixMailbox(fp[, factory]) - - Access to a classic Unix-style mailbox, where all messages are contained in a - single file and separated by ``From`` (a.k.a. ``From_``) lines. The file object - *fp* points to the mailbox file. The optional *factory* parameter is a callable - that should create new message objects. *factory* is called with one argument, - *fp* by the :meth:`next` method of the mailbox object. The default is the - :class:`rfc822.Message` class (see the :mod:`rfc822` module -- and the note - below). - - .. note:: - - For reasons of this module's internal implementation, you will probably want to - open the *fp* object in binary mode. This is especially important on Windows. - - For maximum portability, messages in a Unix-style mailbox are separated by any - line that begins exactly with the string ``'From '`` (note the trailing space) - if preceded by exactly two newlines. Because of the wide-range of variations in - practice, nothing else on the ``From_`` line should be considered. However, the - current implementation doesn't check for the leading two newlines. This is - usually fine for most applications. - - The :class:`UnixMailbox` class implements a more strict version of ``From_`` - line checking, using a regular expression that usually correctly matched - ``From_`` delimiters. It considers delimiter line to be separated by ``From - name time`` lines. For maximum portability, use the - :class:`PortableUnixMailbox` class instead. This class is identical to - :class:`UnixMailbox` except that individual messages are separated by only - ``From`` lines. - - -.. class:: PortableUnixMailbox(fp[, factory]) - - A less-strict version of :class:`UnixMailbox`, which considers only the ``From`` - at the beginning of the line separating messages. The "*name* *time*" portion - of the From line is ignored, to protect against some variations that are - observed in practice. This works since lines in the message which begin with - ``'From '`` are quoted by mail handling software at delivery-time. - - -.. class:: MmdfMailbox(fp[, factory]) - - Access an MMDF-style mailbox, where all messages are contained in a single file - and separated by lines consisting of 4 control-A characters. The file object - *fp* points to the mailbox file. Optional *factory* is as with the - :class:`UnixMailbox` class. - - -.. class:: MHMailbox(dirname[, factory]) - - Access an MH mailbox, a directory with each message in a separate file with a - numeric name. The name of the mailbox directory is passed in *dirname*. - *factory* is as with the :class:`UnixMailbox` class. - - -.. class:: BabylMailbox(fp[, factory]) - - Access a Babyl mailbox, which is similar to an MMDF mailbox. In Babyl format, - each message has two sets of headers, the *original* headers and the *visible* - headers. The original headers appear before a line containing only ``'*** EOOH - ***'`` (End-Of-Original-Headers) and the visible headers appear after the - ``EOOH`` line. Babyl-compliant mail readers will show you only the visible - headers, and :class:`BabylMailbox` objects will return messages containing only - the visible headers. You'll have to do your own parsing of the mailbox file to - get at the original headers. Mail messages start with the EOOH line and end - with a line containing only ``'\037\014'``. *factory* is as with the - :class:`UnixMailbox` class. - -If you wish to use the older mailbox classes with the :mod:`email` module rather -than the deprecated :mod:`rfc822` module, you can do so as follows:: - - import email - import email.Errors - import mailbox - - def msgfactory(fp): - try: - return email.message_from_file(fp) - except email.Errors.MessageParseError: - # Don't return None since that will - # stop the mailbox iterator - return '' - - mbox = mailbox.UnixMailbox(fp, msgfactory) - -Alternatively, if you know your mailbox contains only well-formed MIME messages, -you can simplify this to:: - - import email - import mailbox - - mbox = mailbox.UnixMailbox(fp, email.message_from_file) - - .. _mailbox-examples: Examples |