<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"module-mhlib.html" />
<link rel=
"prev" href=
"module-mailcap.html" />
<link rel=
"parent" href=
"netdata.html" />
<link rel=
"next" href=
"mailbox-objects.html" />
<meta name='aesop' content='information'
/>
<title>12.4 mailbox -- Read various mailbox formats
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"12.3 mailcap "
href=
"module-mailcap.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"12. Internet Data Handling"
href=
"netdata.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"12.4.1 Mailbox Objects"
href=
"mailbox-objects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-mailcap.html">12.3 mailcap
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"netdata.html">12. Internet Data Handling
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"mailbox-objects.html">12.4.1 Mailbox Objects
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION0014400000000000000000">
12.4 <tt class=
"module">mailbox
</tt> --
Read various mailbox formats
</A>
<A NAME=
"module-mailbox"></A>
This module defines a number of classes that allow easy and uniform
access to mail messages in a (
<span class=
"Unix">Unix
</span>) mailbox.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3964' xml:id='l2h-
3964'
class=
"class">UnixMailbox
</tt></b>(
</nobr></td>
<td><var>fp
</var><big>[
</big><var>, factory
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Access to a classic
<span class=
"Unix">Unix
</span>-style mailbox, where all messages are
contained in a single file and separated by
"<tt class="samp
">From </tt>"(a.k.a.
"<tt class="samp
">From_</tt>") lines. The file object
<var>fp
</var> points to the
mailbox file. The optional
<var>factory
</var> parameter is a callable that
should create new message objects.
<var>factory
</var> is called with one
argument,
<var>fp
</var> by the
<tt class=
"method">next()
</tt> method of the mailbox
object. The default is the
<tt class=
"class">rfc822.Message
</tt> class (see the
<tt class=
"module"><a href=
"module-rfc822.html">rfc822
</a></tt> module - and the note below).
<div class=
"note"><b class=
"label">Note:
</b>
For reasons of this module's internal implementation, you will
probably want to open the
<var>fp
</var> object in binary mode. This is
especially important on Windows.
For maximum portability, messages in a
<span class=
"Unix">Unix
</span>-style mailbox are
separated by any line that begins exactly with the string
<code>'From
'
</code> (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
<tt class=
"class">UnixMailbox
</tt> 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
"<tt class="samp
">From <var>name</var> <var>time</var></tt>" lines. For maximum portability,
use the
<tt class=
"class">PortableUnixMailbox
</tt> class instead. This class is
identical to
<tt class=
"class">UnixMailbox
</tt> except that individual messages are
separated by only
"<tt class="samp
">From </tt>" lines.
For more information, see
href=
"http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html"
Netscape Mail on Unix: Why the Content-Length Format is Bad"
Netscape Mail on
<span class=
"Unix">Unix
</span>: Why the Content-Length Format is Bad
</a></em>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3965' xml:id='l2h-
3965'
class=
"class">PortableUnixMailbox
</tt></b>(
</nobr></td>
<td><var>fp
</var><big>[
</big><var>, factory
</var><big>]
</big><var></var>)
</td></tr></table></dt>
A less-strict version of
<tt class=
"class">UnixMailbox
</tt>, which considers only the
"<tt class="samp
">From </tt>" at the beginning of the line separating messages. The
``
<var>name
</var> <var>time
</var>'' 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
<code>'From '
</code> are
quoted by mail handling software at delivery-time.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3966' xml:id='l2h-
3966'
class=
"class">MmdfMailbox
</tt></b>(
</nobr></td>
<td><var>fp
</var><big>[
</big><var>, factory
</var><big>]
</big><var></var>)
</td></tr></table></dt>
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
<var>fp
</var> points to the mailbox file.
Optional
<var>factory
</var> is as with the
<tt class=
"class">UnixMailbox
</tt> class.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3967' xml:id='l2h-
3967'
class=
"class">MHMailbox
</tt></b>(
</nobr></td>
<td><var>dirname
</var><big>[
</big><var>, factory
</var><big>]
</big><var></var>)
</td></tr></table></dt>
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
<var>dirname
</var>.
<var>factory
</var> is as with the
<tt class=
"class">UnixMailbox
</tt> class.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3968' xml:id='l2h-
3968'
class=
"class">Maildir
</tt></b>(
</nobr></td>
<td><var>dirname
</var><big>[
</big><var>, factory
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Access a Qmail mail directory. All new and current mail for the
mailbox specified by
<var>dirname
</var> is made available.
<var>factory
</var> is as with the
<tt class=
"class">UnixMailbox
</tt> class.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3969' xml:id='l2h-
3969'
class=
"class">BabylMailbox
</tt></b>(
</nobr></td>
<td><var>fp
</var><big>[
</big><var>, factory
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Access a Babyl mailbox, which is similar to an MMDF mailbox. In
Babyl format, each message has two sets of headers, the
<em>original
</em> headers and the
<em>visible
</em> headers. The original
headers appear before a line containing only
<code>'*** EOOH ***'
</code>
(End-Of-Original-Headers) and the visible headers appear after the
<code>EOOH
</code> line. Babyl-compliant mail readers will show you only the
visible headers, and
<tt class=
"class">BabylMailbox
</tt> 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
<code>'
\037\014'
</code>.
<var>factory
</var> is as with the
<tt class=
"class">UnixMailbox
</tt> class.
Note that because the
<tt class=
"module"><a href=
"module-rfc822.html">rfc822
</a></tt> module is deprecated, it is
recommended that you use the
<tt class=
"module"><a href=
"module-email.html">email
</a></tt> package to create
message objects from a mailbox. (The default can't be changed for
backwards compatibility reasons.) The safest way to do this is with
<div class=
"verbatim"><pre>
return email.message_from_file(fp)
except email.Errors.MessageParseError:
# Don't return None since that will
# stop the mailbox iterator
mbox = mailbox.UnixMailbox(fp, msgfactory)
The above wrapper is defensive against ill-formed MIME messages in the
mailbox, but you have to be prepared to receive the empty string from
the mailbox's
<tt class=
"function">next()
</tt> method. On the other hand, if you
know your mailbox contains only well-formed MIME messages, you can
<div class=
"verbatim"><pre>
mbox = mailbox.UnixMailbox(fp, email.message_from_file)
<p class=
"heading">See Also:
</p>
<dl compact=
"compact" class=
"seetitle">
<dt><em class=
"citetitle"><a href=
"http://www.qmail.org/man/man5/mbox.html"
file containing mail messages
</a></em></dt>
traditional ``mbox'' mailbox format.
</dd>
<dl compact=
"compact" class=
"seetitle">
<dt><em class=
"citetitle"><a href=
"http://www.qmail.org/man/man5/maildir.html"
directory for incoming mail messages
</a></em></dt>
``maildir'' mailbox format.
</dd>
<dl compact=
"compact" class=
"seetitle">
<dt><em class=
"citetitle"><a href=
"http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html"
Netscape Mail on
<span class=
"Unix">Unix
</span>: Why the Content-Length Format is
<dd>A description of problems with relying on the
<span class=
"mailheader">Content-Length:
</span> header for messages stored in
<p><br /></p><hr class='online-navigation'
/>
<div class='online-navigation'
>
<!--Table of Child-Links-->
<A NAME=
"CHILD_LINKS"><STRONG>Subsections
</STRONG></a>
<LI><A href=
"mailbox-objects.html">12.4.1 Mailbox Objects
</a>
<!--End of Table of Child-Links-->
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"12.3 mailcap "
href=
"module-mailcap.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"12. Internet Data Handling"
href=
"netdata.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"12.4.1 Mailbox Objects"
href=
"mailbox-objects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-mailcap.html">12.3 mailcap
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"netdata.html">12. Internet Data Handling
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"mailbox-objects.html">12.4.1 Mailbox Objects
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.