Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 1 | \declaremodule{standard}{email.Generator} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 2 | \modulesynopsis{Generate flat text email messages from a message structure.} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 3 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 4 | One of the most common tasks is to generate the flat text of the email |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 5 | message represented by a message object structure. You will need to do |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 6 | this if you want to send your message via the \refmodule{smtplib} |
| 7 | module or the \refmodule{nntplib} module, or print the message on the |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 8 | console. Taking a message object structure and producing a flat text |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 9 | document is the job of the \class{Generator} class. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 10 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 11 | Again, as with the \refmodule{email.Parser} module, you aren't limited |
| 12 | to the functionality of the bundled generator; you could write one |
| 13 | from scratch yourself. However the bundled generator knows how to |
| 14 | generate most email in a standards-compliant way, should handle MIME |
| 15 | and non-MIME email messages just fine, and is designed so that the |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 16 | transformation from flat text, to a message structure via the |
| 17 | \class{Parser} class, and back to flat text, is idempotent (the input |
| 18 | is identical to the output). |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 19 | |
| 20 | Here are the public methods of the \class{Generator} class: |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 21 | |
| 22 | \begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{, |
| 23 | maxheaderlen}}} |
| 24 | The constructor for the \class{Generator} class takes a file-like |
| 25 | object called \var{outfp} for an argument. \var{outfp} must support |
| 26 | the \method{write()} method and be usable as the output file in a |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 27 | Python extended print statement. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 28 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 29 | Optional \var{mangle_from_} is a flag that, when \code{True}, puts a |
| 30 | \samp{>} character in front of any line in the body that starts exactly as |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 31 | \samp{From }, i.e. \code{From} followed by a space at the beginning of the |
| 32 | line. This is the only guaranteed portable way to avoid having such |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 33 | lines be mistaken for a Unix mailbox format envelope header separator (see |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 34 | \ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD} |
| 35 | {http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 36 | for details). \var{mangle_from_} defaults to \code{True}, but you |
| 37 | might want to set this to \code{False} if you are not writing Unix |
| 38 | mailbox format files. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 39 | |
| 40 | Optional \var{maxheaderlen} specifies the longest length for a |
| 41 | non-continued header. When a header line is longer than |
| 42 | \var{maxheaderlen} (in characters, with tabs expanded to 8 spaces), |
Barry Warsaw | f8d3bcc | 2003-11-19 02:22:36 +0000 | [diff] [blame] | 43 | the header will be split as defined in the \module{email.Header} |
| 44 | class. Set to zero to disable header wrapping. The default is 78, as |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 45 | recommended (but not required) by \rfc{2822}. |
| 46 | \end{classdesc} |
| 47 | |
| 48 | The other public \class{Generator} methods are: |
| 49 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 50 | \begin{methoddesc}[Generator]{flatten}{msg\optional{, unixfrom}} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 51 | Print the textual representation of the message object structure rooted at |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 52 | \var{msg} to the output file specified when the \class{Generator} |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 53 | instance was created. Subparts are visited depth-first and the |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 54 | resulting text will be properly MIME encoded. |
| 55 | |
| 56 | Optional \var{unixfrom} is a flag that forces the printing of the |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 57 | envelope header delimiter before the first \rfc{2822} header of the |
| 58 | root message object. If the root object has no envelope header, a |
| 59 | standard one is crafted. By default, this is set to \code{False} to |
| 60 | inhibit the printing of the envelope delimiter. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 61 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 62 | Note that for subparts, no envelope header is ever printed. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 63 | |
| 64 | \versionadded{2.2.2} |
| 65 | \end{methoddesc} |
| 66 | |
| 67 | \begin{methoddesc}[Generator]{clone}{fp} |
| 68 | Return an independent clone of this \class{Generator} instance with |
| 69 | the exact same options. |
| 70 | |
| 71 | \versionadded{2.2.2} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 72 | \end{methoddesc} |
| 73 | |
| 74 | \begin{methoddesc}[Generator]{write}{s} |
| 75 | Write the string \var{s} to the underlying file object, |
| 76 | i.e. \var{outfp} passed to \class{Generator}'s constructor. This |
| 77 | provides just enough file-like API for \class{Generator} instances to |
| 78 | be used in extended print statements. |
| 79 | \end{methoddesc} |
| 80 | |
| 81 | As a convenience, see the methods \method{Message.as_string()} and |
| 82 | \code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which |
| 83 | simplify the generation of a formatted string representation of a |
| 84 | message object. For more detail, see \refmodule{email.Message}. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 85 | |
| 86 | The \module{email.Generator} module also provides a derived class, |
| 87 | called \class{DecodedGenerator} which is like the \class{Generator} |
| 88 | base class, except that non-\mimetype{text} parts are substituted with |
| 89 | a format string representing the part. |
| 90 | |
| 91 | \begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{, |
| 92 | maxheaderlen\optional{, fmt}}}} |
| 93 | |
| 94 | This class, derived from \class{Generator} walks through all the |
| 95 | subparts of a message. If the subpart is of main type |
| 96 | \mimetype{text}, then it prints the decoded payload of the subpart. |
| 97 | Optional \var{_mangle_from_} and \var{maxheaderlen} are as with the |
| 98 | \class{Generator} base class. |
| 99 | |
| 100 | If the subpart is not of main type \mimetype{text}, optional \var{fmt} |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 101 | is a format string that is used instead of the message payload. |
| 102 | \var{fmt} is expanded with the following keywords, \samp{\%(keyword)s} |
| 103 | format: |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 104 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 105 | \begin{itemize} |
| 106 | \item \code{type} -- Full MIME type of the non-\mimetype{text} part |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 107 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 108 | \item \code{maintype} -- Main MIME type of the non-\mimetype{text} part |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 109 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 110 | \item \code{subtype} -- Sub-MIME type of the non-\mimetype{text} part |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 111 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 112 | \item \code{filename} -- Filename of the non-\mimetype{text} part |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 113 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 114 | \item \code{description} -- Description associated with the |
| 115 | non-\mimetype{text} part |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 116 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 117 | \item \code{encoding} -- Content transfer encoding of the |
| 118 | non-\mimetype{text} part |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 119 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 120 | \end{itemize} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 121 | |
| 122 | The default value for \var{fmt} is \code{None}, meaning |
| 123 | |
| 124 | \begin{verbatim} |
| 125 | [Non-text (%(type)s) part of message omitted, filename %(filename)s] |
| 126 | \end{verbatim} |
| 127 | |
| 128 | \versionadded{2.2.2} |
| 129 | \end{classdesc} |
| 130 | |
| 131 | \subsubsection{Deprecated methods} |
| 132 | |
| 133 | The following methods are deprecated in \module{email} version 2. |
| 134 | They are documented here for completeness. |
| 135 | |
| 136 | \begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}} |
| 137 | This method is identical to the \method{flatten()} method. |
| 138 | |
| 139 | \deprecated{2.2.2}{Use the \method{flatten()} method instead.} |
| 140 | \end{methoddesc} |