linuxport: Merging in the fruits of my labors (Python VFS)
[xbmc:xbmc-antiquated.git] / xbmc / lib / libPython / Python / Doc / lib / libmailbox.tex
1 \section{\module{mailbox} ---
2          Read various mailbox formats}
3
4 \declaremodule{standard}{mailbox}
5 \modulesynopsis{Read various mailbox formats.}
6
7
8 This module defines a number of classes that allow easy and uniform
9 access to mail messages in a (\UNIX) mailbox.
10
11 \begin{classdesc}{UnixMailbox}{fp\optional{, factory}}
12 Access to a classic \UNIX-style mailbox, where all messages are
13 contained in a single file and separated by \samp{From }
14 (a.k.a.\ \samp{From_}) lines.  The file object \var{fp} points to the
15 mailbox file.  The optional \var{factory} parameter is a callable that
16 should create new message objects.  \var{factory} is called with one
17 argument, \var{fp} by the \method{next()} method of the mailbox
18 object.  The default is the \class{rfc822.Message} class (see the
19 \refmodule{rfc822} module -- and the note below).
20
21 \begin{notice}
22   For reasons of this module's internal implementation, you will
23   probably want to open the \var{fp} object in binary mode.  This is
24   especially important on Windows.
25 \end{notice}
26
27 For maximum portability, messages in a \UNIX-style mailbox are
28 separated by any line that begins exactly with the string \code{'From
29 '} (note the trailing space) if preceded by exactly two newlines.
30 Because of the wide-range of variations in practice, nothing else on
31 the From_ line should be considered.  However, the current
32 implementation doesn't check for the leading two newlines.  This is
33 usually fine for most applications.
34
35 The \class{UnixMailbox} class implements a more strict version of
36 From_ line checking, using a regular expression that usually correctly
37 matched From_ delimiters.  It considers delimiter line to be separated
38 by \samp{From \var{name} \var{time}} lines.  For maximum portability,
39 use the \class{PortableUnixMailbox} class instead.  This class is
40 identical to \class{UnixMailbox} except that individual messages are
41 separated by only \samp{From } lines.
42
43 For more information, see
44 \citetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring
45 Netscape Mail on \UNIX: Why the Content-Length Format is Bad}.
46 \end{classdesc}
47
48 \begin{classdesc}{PortableUnixMailbox}{fp\optional{, factory}}
49 A less-strict version of \class{UnixMailbox}, which considers only the
50 \samp{From } at the beginning of the line separating messages.  The
51 ``\var{name} \var{time}'' portion of the From line is ignored, to
52 protect against some variations that are observed in practice.  This
53 works since lines in the message which begin with \code{'From '} are
54 quoted by mail handling software at delivery-time.
55 \end{classdesc}
56
57 \begin{classdesc}{MmdfMailbox}{fp\optional{, factory}}
58 Access an MMDF-style mailbox, where all messages are contained
59 in a single file and separated by lines consisting of 4 control-A
60 characters.  The file object \var{fp} points to the mailbox file.
61 Optional \var{factory} is as with the \class{UnixMailbox} class.
62 \end{classdesc}
63
64 \begin{classdesc}{MHMailbox}{dirname\optional{, factory}}
65 Access an MH mailbox, a directory with each message in a separate
66 file with a numeric name.
67 The name of the mailbox directory is passed in \var{dirname}.
68 \var{factory} is as with the \class{UnixMailbox} class.
69 \end{classdesc}
70
71 \begin{classdesc}{Maildir}{dirname\optional{, factory}}
72 Access a Qmail mail directory.  All new and current mail for the
73 mailbox specified by \var{dirname} is made available.
74 \var{factory} is as with the \class{UnixMailbox} class.
75 \end{classdesc}
76
77 \begin{classdesc}{BabylMailbox}{fp\optional{, factory}}
78 Access a Babyl mailbox, which is similar to an MMDF mailbox.  In
79 Babyl format, each message has two sets of headers, the
80 \emph{original} headers and the \emph{visible} headers.  The original
81 headers appear before a line containing only \code{'*** EOOH ***'}
82 (End-Of-Original-Headers) and the visible headers appear after the
83 \code{EOOH} line.  Babyl-compliant mail readers will show you only the
84 visible headers, and \class{BabylMailbox} objects will return messages
85 containing only the visible headers.  You'll have to do your own
86 parsing of the mailbox file to get at the original headers.  Mail
87 messages start with the EOOH line and end with a line containing only
88 \code{'\e{}037\e{}014'}.  \var{factory} is as with the
89 \class{UnixMailbox} class.
90 \end{classdesc}
91
92 Note that because the \refmodule{rfc822} module is deprecated, it is
93 recommended that you use the \refmodule{email} package to create
94 message objects from a mailbox.  (The default can't be changed for
95 backwards compatibility reasons.)  The safest way to do this is with
96 bit of code:
97
98 \begin{verbatim}
99 import email
100 import email.Errors
101 import mailbox
102
103 def msgfactory(fp):
104     try:
105         return email.message_from_file(fp)
106     except email.Errors.MessageParseError:
107         # Don't return None since that will
108         # stop the mailbox iterator
109         return ''
110
111 mbox = mailbox.UnixMailbox(fp, msgfactory)
112 \end{verbatim}
113
114 The above wrapper is defensive against ill-formed MIME messages in the
115 mailbox, but you have to be prepared to receive the empty string from
116 the mailbox's \function{next()} method.  On the other hand, if you
117 know your mailbox contains only well-formed MIME messages, you can
118 simplify this to:
119
120 \begin{verbatim}
121 import email
122 import mailbox
123
124 mbox = mailbox.UnixMailbox(fp, email.message_from_file)
125 \end{verbatim}
126
127 \begin{seealso}
128   \seetitle[http://www.qmail.org/man/man5/mbox.html]{mbox -
129             file containing mail messages}{Description of the
130             traditional ``mbox'' mailbox format.}
131   \seetitle[http://www.qmail.org/man/man5/maildir.html]{maildir -
132             directory for incoming mail messages}{Description of the
133             ``maildir'' mailbox format.}
134   \seetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring
135             Netscape Mail on \UNIX: Why the Content-Length Format is
136             Bad}{A description of problems with relying on the
137             \mailheader{Content-Length} header for messages stored in
138             mailbox files.}
139 \end{seealso}
140
141
142 \subsection{Mailbox Objects \label{mailbox-objects}}
143
144 All implementations of mailbox objects are iterable objects, and
145 have one externally visible method.  This method is used by iterators
146 created from mailbox objects and may also be used directly.
147
148 \begin{methoddesc}[mailbox]{next}{}
149 Return the next message in the mailbox, created with the optional
150 \var{factory} argument passed into the mailbox object's constructor.
151 By default this is an \class{rfc822.Message}
152 object (see the \refmodule{rfc822} module).  Depending on the mailbox
153 implementation the \var{fp} attribute of this object may be a true
154 file object or a class instance simulating a file object, taking care
155 of things like message boundaries if multiple mail messages are
156 contained in a single file, etc.  If no more messages are available,
157 this method returns \code{None}.
158 \end{methoddesc}