Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libmailbox.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents bc02c3b09626
children 52420fe67c96
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{mailbox} ---
10253
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
2 Read various mailbox formats}
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{standard}{mailbox}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
5 \modulesynopsis{Read various mailbox formats.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
6
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 This module defines a number of classes that allow easy and uniform
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20194
diff changeset
9 access to mail messages in a (\UNIX) mailbox.
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
11 \begin{classdesc}{UnixMailbox}{fp\optional{, factory}}
16412
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
12 Access to a classic \UNIX-style mailbox, where all messages are
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
13 contained in a single file and separated by \samp{From }
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
14 (a.k.a.\ \samp{From_}) lines. The file object \var{fp} points to the
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
15 mailbox file. The optional \var{factory} parameter is a callable that
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
16 should create new message objects. \var{factory} is called with one
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
17 argument, \var{fp} by the \method{next()} method of the mailbox
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
18 object. The default is the \class{rfc822.Message} class (see the
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
19 \refmodule{rfc822} module).
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
20
16412
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
21 For maximum portability, messages in a \UNIX-style mailbox are
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
22 separated by any line that begins exactly with the string \code{'From
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
23 '} (note the trailing space) if preceded by exactly two newlines.
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
24 Because of the wide-range of variations in practice, nothing else on
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
25 the From_ line should be considered. However, the current
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
26 implementation doesn't check for the leading two newlines. This is
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
27 usually fine for most applications.
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
28
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
29 The \class{UnixMailbox} class implements a more strict version of
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
30 From_ line checking, using a regular expression that usually correctly
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
31 matched From_ delimiters. It considers delimiter line to be separated
16412
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
32 by \samp{From \var{name} \var{time}} lines. For maximum portability,
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
33 use the \class{PortableUnixMailbox} class instead. This class is
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
34 identical to \class{UnixMailbox} except that individual messages are
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
35 separated by only \samp{From } lines.
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
36
16412
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
37 For more information, see
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
38 \citetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
39 Netscape Mail on \UNIX: Why the Content-Length Format is Bad}.
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
40 \end{classdesc}
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
41
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
42 \begin{classdesc}{PortableUnixMailbox}{fp\optional{, factory}}
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
43 A less-strict version of \class{UnixMailbox}, which considers only the
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
44 \samp{From } at the beginning of the line separating messages. The
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
45 ``\var{name} \var{time}'' portion of the From line is ignored, to
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
46 protect against some variations that are observed in practice. This
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
47 works since lines in the message which begin with \code{'From '} are
10ea4060c8dc Adjustments to the text of the UnixMailbox description. Added
Fred Drake <fdrake@acm.org>
parents: 16373
diff changeset
48 quoted by mail handling software well before delivery.
7683
6bf74264b9c0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7303
diff changeset
49 \end{classdesc}
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
50
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
51 \begin{classdesc}{MmdfMailbox}{fp\optional{, factory}}
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 Access an MMDF-style mailbox, where all messages are contained
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 in a single file and separated by lines consisting of 4 control-A
7303
658b742e4350 Don't capitalize identifiers at the beginning of the sentence; re-write to
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
54 characters. The file object \var{fp} points to the mailbox file.
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
55 Optional \var{factory} is as with the \class{UnixMailbox} class.
7683
6bf74264b9c0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7303
diff changeset
56 \end{classdesc}
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
57
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
58 \begin{classdesc}{MHMailbox}{dirname\optional{, factory}}
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 Access an MH mailbox, a directory with each message in a separate
7303
658b742e4350 Don't capitalize identifiers at the beginning of the sentence; re-write to
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
60 file with a numeric name.
658b742e4350 Don't capitalize identifiers at the beginning of the sentence; re-write to
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
61 The name of the mailbox directory is passed in \var{dirname}.
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
62 \var{factory} is as with the \class{UnixMailbox} class.
7683
6bf74264b9c0 Logical markup, using {classdesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7303
diff changeset
63 \end{classdesc}
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
64
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
65 \begin{classdesc}{Maildir}{dirname\optional{, factory}}
10253
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
66 Access a Qmail mail directory. All new and current mail for the
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
67 mailbox specified by \var{dirname} is made available.
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
68 \var{factory} is as with the \class{UnixMailbox} class.
10253
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
69 \end{classdesc}
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
70
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
71 \begin{classdesc}{BabylMailbox}{fp\optional{, factory}}
17415
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
72 Access a Babyl mailbox, which is similar to an MMDF mailbox. In
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
73 Babyl format, each message has two sets of headers, the
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
74 \emph{original} headers and the \emph{visible} headers. The original
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
75 headers appear before a a line containing only \code{'*** EOOH ***'}
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
76 (End-Of-Original-Headers) and the visible headers appear after the
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
77 \code{EOOH} line. Babyl-compliant mail readers will show you only the
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
78 visible headers, and \class{BabylMailbox} objects will return messages
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
79 containing only the visible headers. You'll have to do your own
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
80 parsing of the mailbox file to get at the original headers. Mail
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
81 messages start with the EOOH line and end with a line containing only
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
82 \code{'\e{}037\e{}014'}. \var{factory} is as with the
65a92251d6b8 Added some additional documentation describing how BabylMailbox
Barry Warsaw <barry@python.org>
parents: 16412
diff changeset
83 \class{UnixMailbox} class.
10253
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
84 \end{classdesc}
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
85
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
86
17893
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
87 \begin{seealso}
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
88 \seetitle[http://www.qmail.org/man/man5/mbox.html]{mbox -
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
89 file containing mail messages}{Description of the
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
90 traditional ``mbox'' mailbox format.}
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
91 \seetitle[http://www.qmail.org/man/man5/maildir.html]{maildir -
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
92 directory for incoming mail messages}{Description of the
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
93 ``maildir'' mailbox format.}
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
94 \seetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
95 Netscape Mail on \UNIX: Why the Content-Length Format is
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
96 Bad}{A description of problems with relying on the
18982
8b9d87af61eb Apply the new \mailheader macro where appropriate, and fix a few small
Fred Drake <fdrake@acm.org>
parents: 17893
diff changeset
97 \mailheader{Content-Length} header for messages stored in
8b9d87af61eb Apply the new \mailheader macro where appropriate, and fix a few small
Fred Drake <fdrake@acm.org>
parents: 17893
diff changeset
98 mailbox files.}
17893
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
99 \end{seealso}
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
100
5b097f617173 Add a "See also" section with useful links. More should be added giving
Fred Drake <fdrake@acm.org>
parents: 17661
diff changeset
101
10253
13b45c74e97b Added descriptions for BabylMailbox and Maildir (Qmail) mailbox
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
102 \subsection{Mailbox Objects \label{mailbox-objects}}
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
103
20194
21060318f539 Clarify comments about mailbox objects being iterable.
Fred Drake <fdrake@acm.org>
parents: 19742
diff changeset
104 All implementations of mailbox objects are iterable objects, and
21060318f539 Clarify comments about mailbox objects being iterable.
Fred Drake <fdrake@acm.org>
parents: 19742
diff changeset
105 have one externally visible method. This method is used by iterators
21060318f539 Clarify comments about mailbox objects being iterable.
Fred Drake <fdrake@acm.org>
parents: 19742
diff changeset
106 created from mailbox objects and may also be used directly.
5692
4428f1084b6c Doc for mailbox.tex (Jack)
Guido van Rossum <guido@python.org>
parents:
diff changeset
107
7793
07453140a095 Use methoddesc instead of funcdesc to describe the only method.
Fred Drake <fdrake@acm.org>
parents: 7683
diff changeset
108 \begin{methoddesc}[mailbox]{next}{}
16373
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
109 Return the next message in the mailbox, created with the optional
5dfd7e16c62f Document the two changes to the mailbox.py module:
Barry Warsaw <barry@python.org>
parents: 15149
diff changeset
110 \var{factory} argument passed into the mailbox object's constructor.
19742
2a465b0eb54e typo...
Skip Montanaro <skip@pobox.com>
parents: 18982
diff changeset
111 By default this is an \class{rfc822.Message}
10485
8d115e111a17 Where rfc822.Message is mentioned, add a link to the rfc822 module.
Fred Drake <fdrake@acm.org>
parents: 10257
diff changeset
112 object (see the \refmodule{rfc822} module). Depending on the mailbox
8d115e111a17 Where rfc822.Message is mentioned, add a link to the rfc822 module.
Fred Drake <fdrake@acm.org>
parents: 10257
diff changeset
113 implementation the \var{fp} attribute of this object may be a true
8d115e111a17 Where rfc822.Message is mentioned, add a link to the rfc822 module.
Fred Drake <fdrake@acm.org>
parents: 10257
diff changeset
114 file object or a class instance simulating a file object, taking care
8d115e111a17 Where rfc822.Message is mentioned, add a link to the rfc822 module.
Fred Drake <fdrake@acm.org>
parents: 10257
diff changeset
115 of things like message boundaries if multiple mail messages are
15149
fdc2abdf4777 Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents: 10485
diff changeset
116 contained in a single file, etc. If no more messages are available,
fdc2abdf4777 Fixed a large number of small problems, mostly noted by Detlef Lannert
Fred Drake <fdrake@acm.org>
parents: 10485
diff changeset
117 this method returns \code{None}.
7793
07453140a095 Use methoddesc instead of funcdesc to describe the only method.
Fred Drake <fdrake@acm.org>
parents: 7683
diff changeset
118 \end{methoddesc}