### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1.2 documentation »
- The Python Standard Library »
- 18. Internet Data Handling »
- 18.1. `email` — An email and MIME handling package »

# 18.1.3. `email`: Generating MIME documents

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 `smtplib` module or the `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 `Generator` class.

Again, as with the `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 `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 `Message` constructed by program may result in changes to the `Message` object as defaults are filled in.

Here are the public methods of the `Generator` class, imported from the `email.generator` module:

class `email.generator.``Generator`(outfp, mangle_from_=True, maxheaderlen=78)

  The constructor for the `Generator` class takes a file-like object called outfp for an argument. outfp must support the `write()` method and be usable as the output file for the `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 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 `Header` class. Set to zero to disable header wrapping. The default is 78, as recommended (but not required) by RFC 2822.

  The other public `Generator` methods are:

  `flatten`(msg, unixfrom=False)

    Print the textual representation of the message object structure rooted at msg to the output file specified when the `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.

  `clone`(fp)
    Return an independent clone of this `Generator` instance with the exact same options.
  `write`(s)
    Write the string s to the underlying file object, i.e. outfp passed to `Generator`‘s constructor. This provides just enough file-like API for `Generator` instances to be used in the `print()` function.

As a convenience, see the methods `Message.as_string()` and `str(aMessage)`, a.k.a. `Message.__str__()`, which simplify the generation of a formatted string representation of a message object. For more detail, see `email.message`.

The `email.generator` module also provides a derived class, called `DecodedGenerator` which is like the `Generator` base class, except that non-text parts are substituted with a format string representing the part.

`DecodedGenerator(outfp[, mangle_from_=True, maxheaderlen=78, fmt=None)`

  This class, derived from `Generator` walks through all the subparts of a message. If the subpart is of main type text, then it prints the decoded payload of the subpart. Optional _mangle_from_ and maxheaderlen are as with the `Generator` base class.

  If the subpart is not of main type 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-text part
  - `maintype` – Main MIME type of the non-text part
  - `subtype` – Sub-MIME type of the non-text part
  - `filename` – Filename of the non-text part
  - `description` – Description associated with the non-text part
  - `encoding` – Content transfer encoding of the non-text part

  The default value for fmt is `None`, meaning

      [Non-text (%(type)s) part of message omitted, filename %(filename)s]

### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1.2 documentation »
- The Python Standard Library »
- 18. Internet Data Handling »
- 18.1. `email` — An email and MIME handling package »