1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
\declaremodule{standard}{email.Generator}
\modulesynopsis{Generate flat text email messages from a message object tree.}
One of the most common tasks is to generate the flat text of the email
message represented by a message object tree. You will need to do
this if you want to send your message via the \refmodule{smtplib}
module or the \refmodule{nntplib} module, or print the message on the
console. Taking a message object tree and producing a flat text
document is the job of the \class{Generator} class.
Again, as with the \refmodule{email.Parser} module, you aren't limited
to the functionality of the bundled generator; you could write one
from scratch yourself. However the bundled generator knows how to
generate most email in a standards-compliant way, should handle MIME
and non-MIME email messages just fine, and is designed so that the
transformation from flat text, to an object tree via the
\class{Parser} class,
and back to flat text, be idempotent (the input is identical to the
output).
Here are the public methods of the \class{Generator} class:
\begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
maxheaderlen}}}
The constructor for the \class{Generator} class takes a file-like
object called \var{outfp} for an argument. \var{outfp} must support
the \method{write()} method and be usable as the output file in a
Python 2.0 extended print statement.
Optional \var{mangle_from_} is a flag that, when true, puts a ``>''
character in front of any line in the body that starts exactly as
\samp{From } (i.e. \code{From} followed by a space at the front of the
line). This is the only guaranteed portable way to avoid having such
lines be mistaken for \emph{Unix-From} headers (see
\ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
for details).
Optional \var{maxheaderlen} specifies the longest length for a
non-continued header. When a header line is longer than
\var{maxheaderlen} (in characters, with tabs expanded to 8 spaces),
the header will be broken on semicolons and continued as per
\rfc{2822}. If no semicolon is found, then the header is left alone.
Set to zero to disable wrapping headers. Default is 78, as
recommended (but not required) by \rfc{2822}.
\end{classdesc}
The other public \class{Generator} methods are:
\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
Print the textual representation of the message object tree rooted at
\var{msg} to the output file specified when the \class{Generator}
instance was created. Sub-objects are visited depth-first and the
resulting text will be properly MIME encoded.
Optional \var{unixfrom} is a flag that forces the printing of the
\emph{Unix-From} (a.k.a. envelope header or \code{From_} header)
delimiter before the first \rfc{2822} header of the root message
object. If the root object has no \emph{Unix-From} header, a standard
one is crafted. By default, this is set to 0 to inhibit the printing
of the \emph{Unix-From} delimiter.
Note that for sub-objects, no \emph{Unix-From} header is ever printed.
\end{methoddesc}
\begin{methoddesc}[Generator]{write}{s}
Write the string \var{s} to the underlying file object,
i.e. \var{outfp} passed to \class{Generator}'s constructor. This
provides just enough file-like API for \class{Generator} instances to
be used in extended print statements.
\end{methoddesc}
As a convenience, see the methods \method{Message.as_string()} and
\code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which
simplify the generation of a formatted string representation of a
message object. For more detail, see \refmodule{email.Message}.
|
