rest25/library/email.generator.rst => rest262/library/email.generator.rst
n1+:mod:`email`: Generating MIME documents
2+---------------------------------------
3+ 
1.. module:: email.generator
2   :synopsis: Generate flat text email messages from a message structure.
3
4
5One of the most common tasks is to generate the flat text of the email message
6represented by a message object structure.  You will need to do this if you want
7to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
8or print the message on the console.  Taking a message object structure and
26   *outfp* for an argument.  *outfp* must support the :meth:`write` method and be
27   usable as the output file in a Python extended print statement.
28
29   Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
30   front of any line in the body that starts exactly as ``From``, i.e. ``From``
31   followed by a space at the beginning of the line.  This is the only guaranteed
32   portable way to avoid having such lines be mistaken for a Unix mailbox format
33   envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD
n34-   <http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html>`_
n37+   <http://www.jwz.org/doc/content-length.html>`_ for details).  *mangle_from_*
35-   for details).  *mangle_from_* defaults to ``True``, but you might want to set
38+   defaults to ``True``, but you might want to set this to ``False`` if you are not
36-   this to ``False`` if you are not writing Unix mailbox format files.
39+   writing Unix mailbox format files.
37
38   Optional *maxheaderlen* specifies the longest length for a non-continued header.
39   When a header line is longer than *maxheaderlen* (in characters, with tabs
40   expanded to 8 spaces), the header will be split as defined in the
41   :mod:`email.header.Header` class.  Set to zero to disable header wrapping.  The
42   default is 78, as recommended (but not required) by :rfc:`2822`.
43
n44-The other public :class:`Generator` methods are:
n47+   The other public :class:`Generator` methods are:
45
46
n47-.. method:: Generator.flatten(msg[, unixfrom])
n50+   .. method:: flatten(msg[, unixfrom])
48
n49-   Print the textual representation of the message object structure rooted at *msg*
n52+      Print the textual representation of the message object structure rooted at
50-   to the output file specified when the :class:`Generator` instance was created.
53+      *msg* to the output file specified when the :class:`Generator` instance
51-   Subparts are visited depth-first and the resulting text will be properly MIME
54+      was created.  Subparts are visited depth-first and the resulting text will
52-   encoded.
55+      be properly MIME encoded.
53
n54-   Optional *unixfrom* is a flag that forces the printing of the envelope header
n57+      Optional *unixfrom* is a flag that forces the printing of the envelope
55-   delimiter before the first :rfc:`2822` header of the root message object.  If
58+      header delimiter before the first :rfc:`2822` header of the root message
56-   the root object has no envelope header, a standard one is crafted.  By default,
59+      object.  If the root object has no envelope header, a standard one is
57-   this is set to ``False`` to inhibit the printing of the envelope delimiter.
60+      crafted.  By default, this is set to ``False`` to inhibit the printing of
61+      the envelope delimiter.
58
n59-   Note that for subparts, no envelope header is ever printed.
n63+      Note that for subparts, no envelope header is ever printed.
60
n61-   .. versionadded:: 2.2.2
n65+      .. versionadded:: 2.2.2
62
63
n64-.. method:: Generator.clone(fp)
n68+   .. method:: clone(fp)
65
n66-   Return an independent clone of this :class:`Generator` instance with the exact
n70+      Return an independent clone of this :class:`Generator` instance with the
67-   same options.
71+      exact same options.
68
n69-   .. versionadded:: 2.2.2
n73+      .. versionadded:: 2.2.2
70
71
n72-.. method:: Generator.write(s)
n76+   .. method:: write(s)
73
n74-   Write the string *s* to the underlying file object, i.e. *outfp* passed to
n78+      Write the string *s* to the underlying file object, i.e. *outfp* passed to
75-   :class:`Generator`'s constructor.  This provides just enough file-like API for
79+      :class:`Generator`'s constructor.  This provides just enough file-like API
76-   :class:`Generator` instances to be used in extended print statements.
80+      for :class:`Generator` instances to be used in extended print statements.
77
78As a convenience, see the methods :meth:`Message.as_string` and
79``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation
80of a formatted string representation of a message object.  For more detail, see
81:mod:`email.message`.
82
83The :mod:`email.generator` module also provides a derived class, called
84:class:`DecodedGenerator` which is like the :class:`Generator` base class,
92   message.  If the subpart is of main type :mimetype:`text`, then it prints the
93   decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
94   as with the :class:`Generator` base class.
95
96   If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
97   string that is used instead of the message payload. *fmt* is expanded with the
98   following keywords, ``%(keyword)s`` format:
99
n100-* ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
n104+   * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
101
n102-* ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
n106+   * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
103
n104-* ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
n108+   * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
105
n106-* ``filename`` -- Filename of the non-\ :mimetype:`text` part
n110+   * ``filename`` -- Filename of the non-\ :mimetype:`text` part
107
n108-* ``description`` -- Description associated with the non-\ :mimetype:`text` part
n112+   * ``description`` -- Description associated with the non-\ :mimetype:`text` part
109
t110-* ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
t114+   * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
111
112   The default value for *fmt* is ``None``, meaning ::
113
114      [Non-text (%(type)s) part of message omitted, filename %(filename)s]
115
116   .. versionadded:: 2.2.2
117
118.. versionchanged:: 2.5
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op