mirror of
https://github.com/python/cpython.git
synced 2025-10-31 10:26:02 +00:00
234 lines
11 KiB
ReStructuredText
234 lines
11 KiB
ReStructuredText
:mod:`email.generator`: Generating MIME documents
|
|
-------------------------------------------------
|
|
|
|
.. module:: email.generator
|
|
:synopsis: Generate flat text email messages from a message structure.
|
|
|
|
|
|
One of the most common tasks is to generate the flat text of the email message
|
|
represented by a message object structure. You will need to do this if you want
|
|
to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
|
|
or print the message on the console. Taking a message object structure and
|
|
producing a flat text document is the job of the :class:`Generator` class.
|
|
|
|
Again, as with the :mod:`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 a message
|
|
structure via the :class:`~email.parser.Parser` class, and back to flat text,
|
|
is idempotent (the input is identical to the output) [#]_. On the other hand,
|
|
using the Generator on a :class:`~email.message.Message` constructed by program
|
|
may result in changes to the :class:`~email.message.Message` object as defaults
|
|
are filled in.
|
|
|
|
:class:`bytes` output can be generated using the :class:`BytesGenerator` class.
|
|
If the message object structure contains non-ASCII bytes, this generator's
|
|
:meth:`~BytesGenerator.flatten` method will emit the original bytes. Parsing a
|
|
binary message and then flattening it with :class:`BytesGenerator` should be
|
|
idempotent for standards compliant messages.
|
|
|
|
Here are the public methods of the :class:`Generator` class, imported from the
|
|
:mod:`email.generator` module:
|
|
|
|
|
|
.. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78, *, policy=None)
|
|
|
|
The constructor for the :class:`Generator` class takes a :term:`file-like object`
|
|
called *outfp* for an argument. *outfp* must support the :meth:`write` method
|
|
and be usable as the output file for the :func:`print` function.
|
|
|
|
Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
|
|
front of any line in the body that starts exactly as ``From``, i.e. ``From``
|
|
followed by a space at the beginning of the line. This is the only guaranteed
|
|
portable way to avoid having such lines be mistaken for a Unix mailbox format
|
|
envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD
|
|
<http://www.jwz.org/doc/content-length.html>`_ for details). *mangle_from_*
|
|
defaults to ``True``, but you might want to set this to ``False`` if you are not
|
|
writing Unix mailbox format files.
|
|
|
|
Optional *maxheaderlen* specifies the longest length for a non-continued header.
|
|
When a header line is longer than *maxheaderlen* (in characters, with tabs
|
|
expanded to 8 spaces), the header will be split as defined in the
|
|
:class:`~email.header.Header` class. Set to zero to disable header wrapping.
|
|
The default is 78, as recommended (but not required) by :rfc:`2822`.
|
|
|
|
The *policy* keyword specifies a :mod:`~email.policy` object that controls a
|
|
number of aspects of the generator's operation. If no *policy* is specified,
|
|
then the *policy* attached to the message object passed to :attr:`flatten`
|
|
is used.
|
|
|
|
.. versionchanged:: 3.3 Added the *policy* keyword.
|
|
|
|
The other public :class:`Generator` methods are:
|
|
|
|
|
|
.. method:: flatten(msg, unixfrom=False, linesep=None)
|
|
|
|
Print the textual representation of the message object structure rooted at
|
|
*msg* to the output file specified when the :class:`Generator` instance
|
|
was created. Subparts are visited depth-first and the resulting text will
|
|
be properly MIME encoded.
|
|
|
|
Optional *unixfrom* is a flag that forces the printing of the envelope
|
|
header delimiter before the first :rfc:`2822` header of the root message
|
|
object. If the root object has no envelope header, a standard one is
|
|
crafted. By default, this is set to ``False`` to inhibit the printing of
|
|
the envelope delimiter.
|
|
|
|
Note that for subparts, no envelope header is ever printed.
|
|
|
|
Optional *linesep* specifies the line separator character used to
|
|
terminate lines in the output. If specified it overrides the value
|
|
specified by the *msg*\'s or ``Generator``\'s ``policy``.
|
|
|
|
Because strings cannot represent non-ASCII bytes, if the policy that
|
|
applies when ``flatten`` is run has :attr:`~email.policy.Policy.cte_type`
|
|
set to ``8bit``, ``Generator`` will operate as if it were set to
|
|
``7bit``. This means that messages parsed with a Bytes parser that have
|
|
a :mailheader:`Content-Transfer-Encoding` of ``8bit`` will be converted
|
|
to a use a ``7bit`` Content-Transfer-Encoding. Non-ASCII bytes in the
|
|
headers will be :rfc:`2047` encoded with a charset of ``unknown-8bit``.
|
|
|
|
.. versionchanged:: 3.2
|
|
Added support for re-encoding ``8bit`` message bodies, and the
|
|
*linesep* argument.
|
|
|
|
.. method:: clone(fp)
|
|
|
|
Return an independent clone of this :class:`Generator` instance with the
|
|
exact same options.
|
|
|
|
.. method:: write(s)
|
|
|
|
Write the string *s* to the underlying file object, i.e. *outfp* passed to
|
|
:class:`Generator`'s constructor. This provides just enough file-like API
|
|
for :class:`Generator` instances to be used in the :func:`print` function.
|
|
|
|
As a convenience, see the :class:`~email.message.Message` methods
|
|
:meth:`~email.message.Message.as_string` and ``str(aMessage)``, a.k.a.
|
|
:meth:`~email.message.Message.__str__`, which simplify the generation of a
|
|
formatted string representation of a message object. For more detail, see
|
|
:mod:`email.message`.
|
|
|
|
.. class:: BytesGenerator(outfp, mangle_from_=True, maxheaderlen=78, *, \
|
|
policy=policy.default)
|
|
|
|
The constructor for the :class:`BytesGenerator` class takes a binary
|
|
:term:`file-like object` called *outfp* for an argument. *outfp* must
|
|
support a :meth:`write` method that accepts binary data.
|
|
|
|
Optional *mangle_from_* is a flag that, when ``True``, puts a ``>``
|
|
character in front of any line in the body that starts exactly as ``From``,
|
|
i.e. ``From`` followed by a space at the beginning of the line. This is the
|
|
only guaranteed portable way to avoid having such lines be mistaken for a
|
|
Unix mailbox format envelope header separator (see `WHY THE CONTENT-LENGTH
|
|
FORMAT IS BAD <http://www.jwz.org/doc/content-length.html>`_ for details).
|
|
*mangle_from_* defaults to ``True``, but you might want to set this to
|
|
``False`` if you are not writing Unix mailbox format files.
|
|
|
|
Optional *maxheaderlen* specifies the longest length for a non-continued
|
|
header. When a header line is longer than *maxheaderlen* (in characters,
|
|
with tabs expanded to 8 spaces), the header will be split as defined in the
|
|
:class:`~email.header.Header` class. Set to zero to disable header
|
|
wrapping. The default is 78, as recommended (but not required) by
|
|
:rfc:`2822`.
|
|
|
|
The *policy* keyword specifies a :mod:`~email.policy` object that controls a
|
|
number of aspects of the generator's operation. The default policy
|
|
maintains backward compatibility.
|
|
|
|
.. versionchanged:: 3.3 Added the *policy* keyword.
|
|
|
|
The other public :class:`BytesGenerator` methods are:
|
|
|
|
|
|
.. method:: flatten(msg, unixfrom=False, linesep=None)
|
|
|
|
Print the textual representation of the message object structure rooted
|
|
at *msg* to the output file specified when the :class:`BytesGenerator`
|
|
instance was created. Subparts are visited depth-first and the resulting
|
|
text will be properly MIME encoded. If the :mod:`~email.policy` option
|
|
:attr:`~email.policy.Policy.cte_type` is ``8bit`` (the default),
|
|
then any bytes with the high bit set in the original parsed message that
|
|
have not been modified will be copied faithfully to the output. If
|
|
``cte_type`` is ``7bit``, the bytes will be converted as needed
|
|
using an ASCII-compatible Content-Transfer-Encoding. In particular,
|
|
RFC-invalid non-ASCII bytes in headers will be encoded using the MIME
|
|
``unknown-8bit`` character set, thus rendering them RFC-compliant.
|
|
|
|
.. XXX: There should be a complementary option that just does the RFC
|
|
compliance transformation but leaves CTE 8bit parts alone.
|
|
|
|
Messages parsed with a Bytes parser that have a
|
|
:mailheader:`Content-Transfer-Encoding` of 8bit will be reconstructed
|
|
as 8bit if they have not been modified.
|
|
|
|
Optional *unixfrom* is a flag that forces the printing of the envelope
|
|
header delimiter before the first :rfc:`2822` header of the root message
|
|
object. If the root object has no envelope header, a standard one is
|
|
crafted. By default, this is set to ``False`` to inhibit the printing of
|
|
the envelope delimiter.
|
|
|
|
Note that for subparts, no envelope header is ever printed.
|
|
|
|
Optional *linesep* specifies the line separator character used to
|
|
terminate lines in the output. If specified it overrides the value
|
|
specified by the ``Generator``\ 's ``policy``.
|
|
|
|
.. method:: clone(fp)
|
|
|
|
Return an independent clone of this :class:`BytesGenerator` instance with
|
|
the exact same options.
|
|
|
|
.. method:: write(s)
|
|
|
|
Write the string *s* to the underlying file object. *s* is encoded using
|
|
the ``ASCII`` codec and written to the *write* method of the *outfp*
|
|
*outfp* passed to the :class:`BytesGenerator`'s constructor. This
|
|
provides just enough file-like API for :class:`BytesGenerator` instances
|
|
to be used in the :func:`print` function.
|
|
|
|
.. versionadded:: 3.2
|
|
|
|
The :mod:`email.generator` module also provides a derived class, called
|
|
:class:`DecodedGenerator` which is like the :class:`Generator` base class,
|
|
except that non-\ :mimetype:`text` parts are substituted with a format string
|
|
representing the part.
|
|
|
|
|
|
.. class:: DecodedGenerator(outfp, mangle_from_=True, maxheaderlen=78, fmt=None)
|
|
|
|
This class, derived from :class:`Generator` walks through all the subparts of a
|
|
message. If the subpart is of main type :mimetype:`text`, then it prints the
|
|
decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
|
|
as with the :class:`Generator` base class.
|
|
|
|
If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
|
|
string that is used instead of the message payload. *fmt* is expanded with the
|
|
following keywords, ``%(keyword)s`` format:
|
|
|
|
* ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
|
|
|
|
* ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
|
|
|
|
* ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
|
|
|
|
* ``filename`` -- Filename of the non-\ :mimetype:`text` part
|
|
|
|
* ``description`` -- Description associated with the non-\ :mimetype:`text` part
|
|
|
|
* ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
|
|
|
|
The default value for *fmt* is ``None``, meaning ::
|
|
|
|
[Non-text (%(type)s) part of message omitted, filename %(filename)s]
|
|
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#] This statement assumes that you use the appropriate setting for the
|
|
``unixfrom`` argument, and that you set maxheaderlen=0 (which will
|
|
preserve whatever the input line lengths were). It is also not strictly
|
|
true, since in many cases runs of whitespace in headers are collapsed
|
|
into single blanks. The latter is a bug that will eventually be fixed.
|