Doc/library/mimify.rst

   1
   2 :mod:`mimify` --- MIME processing of mail messages
   3 ==================================================
   4
   5 .. module:: mimify
   6    :synopsis: Mimification and unmimification of mail messages.
   7    :deprecated:
   8
   9
  10 .. deprecated:: 2.3
  11    The :mod:`email` package should be used in preference to the :mod:`mimify`
  12    module.  This module is present only to maintain backward compatibility.
  13
  14 The :mod:`mimify` module defines two functions to convert mail messages to and
  15 from MIME format.  The mail message can be either a simple message or a
  16 so-called multipart message.  Each part is treated separately. Mimifying (a part
  17 of) a message entails encoding the message as quoted-printable if it contains
  18 any characters that cannot be represented using 7-bit ASCII.  Unmimifying (a
  19 part of) a message entails undoing the quoted-printable encoding.  Mimify and
  20 unmimify are especially useful when a message has to be edited before being
  21 sent.  Typical use would be::
  22
  23    unmimify message
  24    edit message
  25    mimify message
  26    send message
  27
  28 The modules defines the following user-callable functions and user-settable
  29 variables:
  30
  31
  32 .. function:: mimify(infile, outfile)
  33
  34    Copy the message in *infile* to *outfile*, converting parts to quoted-printable
  35    and adding MIME mail headers when necessary. *infile* and *outfile* can be file
  36    objects (actually, any object that has a :meth:`readline` method (for *infile*)
  37    or a :meth:`write` method (for *outfile*)) or strings naming the files. If
  38    *infile* and *outfile* are both strings, they may have the same value.
  39
  40
  41 .. function:: unmimify(infile, outfile[, decode_base64])
  42
  43    Copy the message in *infile* to *outfile*, decoding all quoted-printable parts.
  44    *infile* and *outfile* can be file objects (actually, any object that has a
  45    :meth:`readline` method (for *infile*) or a :meth:`write` method (for
  46    *outfile*)) or strings naming the files.  If *infile* and *outfile* are both
  47    strings, they may have the same value. If the *decode_base64* argument is
  48    provided and tests true, any parts that are coded in the base64 encoding are
  49    decoded as well.
  50
  51
  52 .. function:: mime_decode_header(line)
  53
  54    Return a decoded version of the encoded header line in *line*. This only
  55    supports the ISO 8859-1 charset (Latin-1).
  56
  57
  58 .. function:: mime_encode_header(line)
  59
  60    Return a MIME-encoded version of the header line in *line*.
  61
  62
  63 .. data:: MAXLEN
  64
  65    By default, a part will be encoded as quoted-printable when it contains any
  66    non-ASCII characters (characters with the 8th bit set), or if there are any
  67    lines longer than :const:`MAXLEN` characters (default value 200).
  68
  69
  70 .. data:: CHARSET
  71
  72    When not specified in the mail headers, a character set must be filled in.  The
  73    string used is stored in :const:`CHARSET`, and the default value is ISO-8859-1
  74    (also known as Latin1 (latin-one)).
  75
  76 This module can also be used from the command line.  Usage is as follows::
  77
  78    mimify.py -e [-l length] [infile [outfile]]
  79    mimify.py -d [-b] [infile [outfile]]
  80
  81 to encode (mimify) and decode (unmimify) respectively.  *infile* defaults to
  82 standard input, *outfile* defaults to standard output. The same file can be
  83 specified for input and output.
  84
  85 If the **-l** option is given when encoding, if there are any lines longer than
  86 the specified *length*, the containing part will be encoded.
  87
  88 If the **-b** option is given when decoding, any base64 parts will be decoded as
  89 well.
  90
  91
  92 .. seealso::
  93
  94    Module :mod:`quopri`
  95       Encode and decode MIME quoted-printable files.
  96