18.1.9. "email.utils": Miscellaneous utilities
**********************************************

There are several useful utilities provided in the "email.utils"
module:

email.utils.quote(str)

   Return a new string with backslashes in *str* replaced by two
   backslashes, and double quotes replaced by backslash-double quote.

email.utils.unquote(str)

   Return a new string which is an *unquoted* version of *str*. If
   *str* ends and begins with double quotes, they are stripped off.
   Likewise if *str* ends and begins with angle brackets, they are
   stripped off.

email.utils.parseaddr(address)

   Parse address – which should be the value of some address-
   containing field such as *To* or *Cc* – into its constituent
   *realname* and *email address* parts.  Returns a tuple of that
   information, unless the parse fails, in which case a 2-tuple of
   "('', '')" is returned.

email.utils.formataddr(pair)

   The inverse of "parseaddr()", this takes a 2-tuple of the form
   "(realname, email_address)" and returns the string value suitable
   for a *To* or *Cc* header.  If the first element of *pair* is
   false, then the second element is returned unmodified.

email.utils.getaddresses(fieldvalues)

   This method returns a list of 2-tuples of the form returned by
   "parseaddr()". *fieldvalues* is a sequence of header field values
   as might be returned by "Message.get_all".  Here’s a simple example
   that gets all the recipients of a message:

      from email.utils import getaddresses

      tos = msg.get_all('to', [])
      ccs = msg.get_all('cc', [])
      resent_tos = msg.get_all('resent-to', [])
      resent_ccs = msg.get_all('resent-cc', [])
      all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

email.utils.parsedate(date)

   Attempts to parse a date according to the rules in **RFC 2822**.
   however, some mailers don’t follow that format as specified, so
   "parsedate()" tries to guess correctly in such cases.  *date* is a
   string containing an **RFC 2822** date, such as  ""Mon, 20 Nov 1995
   19:12:08 -0500"".  If it succeeds in parsing the date,
   "parsedate()" returns a 9-tuple that can be passed directly to
   "time.mktime()"; otherwise "None" will be returned.  Note that
   indexes 6, 7, and 8 of the result tuple are not usable.

email.utils.parsedate_tz(date)

   Performs the same function as "parsedate()", but returns either
   "None" or a 10-tuple; the first 9 elements make up a tuple that can
   be passed directly to "time.mktime()", and the tenth is the offset
   of the date’s timezone from UTC (which is the official term for
   Greenwich Mean Time) [1].  If the input string has no timezone, the
   last element of the tuple returned is "None".  Note that indexes 6,
   7, and 8 of the result tuple are not usable.

email.utils.mktime_tz(tuple)

   Turn a 10-tuple as returned by "parsedate_tz()" into a UTC
   timestamp (seconds since the Epoch).  If the timezone item in the
   tuple is "None", assume local time.

email.utils.formatdate([timeval[, localtime][, usegmt]])

   Returns a date string as per **RFC 2822**, e.g.:

      Fri, 09 Nov 2001 01:08:47 -0000

   Optional *timeval* if given is a floating point time value as
   accepted by "time.gmtime()" and "time.localtime()", otherwise the
   current time is used.

   Optional *localtime* is a flag that when "True", interprets
   *timeval*, and returns a date relative to the local timezone
   instead of UTC, properly taking daylight savings time into account.
   The default is "False" meaning UTC is used.

   Optional *usegmt* is a flag that when "True", outputs a  date
   string with the timezone as an ascii string "GMT", rather than a
   numeric "-0000". This is needed for some protocols (such as HTTP).
   This only applies when *localtime* is "False".  The default is
   "False".

   New in version 2.4.

email.utils.make_msgid([idstring])

   Returns a string suitable for an **RFC 2822**-compliant *Message-
   ID* header.  Optional *idstring* if given, is a string used to
   strengthen the uniqueness of the message id.

email.utils.decode_rfc2231(s)

   Decode the string *s* according to **RFC 2231**.

email.utils.encode_rfc2231(s[, charset[, language]])

   Encode the string *s* according to **RFC 2231**.  Optional
   *charset* and *language*, if given is the character set name and
   language name to use.  If neither is given, *s* is returned as-is.
   If *charset* is given but *language* is not, the string is encoded
   using the empty string for *language*.

email.utils.collapse_rfc2231_value(value[, errors[, fallback_charset]])

   When a header parameter is encoded in **RFC 2231** format,
   "Message.get_param" may return a 3-tuple containing the character
   set, language, and value.  "collapse_rfc2231_value()" turns this
   into a unicode string.  Optional *errors* is passed to the *errors*
   argument of the built-in "unicode()" function; it defaults to
   "replace".  Optional *fallback_charset* specifies the character set
   to use if the one in the **RFC 2231** header is not known by
   Python; it defaults to "us-ascii".

   For convenience, if the *value* passed to
   "collapse_rfc2231_value()" is not a tuple, it should be a string
   and it is returned unquoted.

email.utils.decode_params(params)

   Decode parameters list according to **RFC 2231**.  *params* is a
   sequence of 2-tuples containing elements of the form "(content-
   type, string-value)".

Changed in version 2.4: The "dump_address_pair()" function has been
removed; use "formataddr()" instead.

Changed in version 2.4: The "decode()" function has been removed; use
the "Header.decode_header" method instead.

Changed in version 2.4: The "encode()" function has been removed; use
the "Header.encode" method instead.

-[ Footnotes ]-

[1] Note that the sign of the timezone offset is the opposite of
    the sign of the "time.timezone" variable for the same timezone;
    the latter variable follows the POSIX standard while this module
    follows **RFC 2822**.