This document is for an old version of Python that is no longer supported. You should upgrade and read the Python documentation for the current stable release.

# 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.