Doc/lib/emailutil.tex

   1 \declaremodule{standard}{email.Utils}
   2 \modulesynopsis{Miscellaneous email package utilities.}
   3
   4 There are several useful utilities provided with the \module{email}
   5 package.
   6
   7 \begin{funcdesc}{quote}{str}
   8 Return a new string with backslashes in \var{str} replaced by two
   9 backslashes, and double quotes replaced by backslash-double quote.
  10 \end{funcdesc}
  11
  12 \begin{funcdesc}{unquote}{str}
  13 Return a new string which is an \emph{unquoted} version of \var{str}.
  14 If \var{str} ends and begins with double quotes, they are stripped
  15 off.  Likewise if \var{str} ends and begins with angle brackets, they
  16 are stripped off.
  17 \end{funcdesc}
  18
  19 \begin{funcdesc}{parseaddr}{address}
  20 Parse address -- which should be the value of some address-containing
  21 field such as \mailheader{To} or \mailheader{Cc} -- into its constituent
  22 \emph{realname} and \emph{email address} parts.  Returns a tuple of that
  23 information, unless the parse fails, in which case a 2-tuple of
  24 \code{('', '')} is returned.
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{formataddr}{pair}
  28 The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
  29 \code{(realname, email_address)} and returns the string value suitable
  30 for a \mailheader{To} or \mailheader{Cc} header.  If the first element of
  31 \var{pair} is false, then the second element is returned unmodified.
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{getaddresses}{fieldvalues}
  35 This method returns a list of 2-tuples of the form returned by
  36 \code{parseaddr()}.  \var{fieldvalues} is a sequence of header field
  37 values as might be returned by \method{Message.get_all()}.  Here's a
  38 simple example that gets all the recipients of a message:
  39
  40 \begin{verbatim}
  41 from email.Utils import getaddresses
  42
  43 tos = msg.get_all('to', [])
  44 ccs = msg.get_all('cc', [])
  45 resent_tos = msg.get_all('resent-to', [])
  46 resent_ccs = msg.get_all('resent-cc', [])
  47 all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
  48 \end{verbatim}
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{parsedate}{date}
  52 Attempts to parse a date according to the rules in \rfc{2822}.
  53 however, some mailers don't follow that format as specified, so
  54 \function{parsedate()} tries to guess correctly in such cases.
  55 \var{date} is a string containing an \rfc{2822} date, such as
  56 \code{"Mon, 20 Nov 1995 19:12:08 -0500"}.  If it succeeds in parsing
  57 the date, \function{parsedate()} returns a 9-tuple that can be passed
  58 directly to \function{time.mktime()}; otherwise \code{None} will be
  59 returned.  Note that fields 6, 7, and 8 of the result tuple are not
  60 usable.
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{parsedate_tz}{date}
  64 Performs the same function as \function{parsedate()}, but returns
  65 either \code{None} or a 10-tuple; the first 9 elements make up a tuple
  66 that can be passed directly to \function{time.mktime()}, and the tenth
  67 is the offset of the date's timezone from UTC (which is the official
  68 term for Greenwich Mean Time)\footnote{Note that the sign of the timezone
  69 offset is the opposite of the sign of the \code{time.timezone}
  70 variable for the same timezone; the latter variable follows the
  71 \POSIX{} standard while this module follows \rfc{2822}.}.  If the input
  72 string has no timezone, the last element of the tuple returned is
  73 \code{None}.  Note that fields 6, 7, and 8 of the result tuple are not
  74 usable.
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{mktime_tz}{tuple}
  78 Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
  79 timestamp.  It the timezone item in the tuple is \code{None}, assume
  80 local time.  Minor deficiency: \function{mktime_tz()} interprets the
  81 first 8 elements of \var{tuple} as a local time and then compensates
  82 for the timezone difference.  This may yield a slight error around
  83 changes in daylight savings time, though not worth worrying about for
  84 common use.
  85 \end{funcdesc}
  86
  87 \begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}}}
  88 Returns a date string as per \rfc{2822}, e.g.:
  89
  90 \begin{verbatim}
  91 Fri, 09 Nov 2001 01:08:47 -0000
  92 \end{verbatim}
  93
  94 Optional \var{timeval} if given is a floating point time value as
  95 accepted by \function{time.gmtime()} and \function{time.localtime()},
  96 otherwise the current time is used.
  97
  98 Optional \var{localtime} is a flag that when \code{True}, interprets
  99 \var{timeval}, and returns a date relative to the local timezone
 100 instead of UTC, properly taking daylight savings time into account.
 101 The default is \code{False} meaning UTC is used.
 102 \end{funcdesc}
 103
 104 \begin{funcdesc}{make_msgid}{\optional{idstring}}
 105 Returns a string suitable for an \rfc{2822}-compliant
 106 \mailheader{Message-ID} header.  Optional \var{idstring} if given, is
 107 a string used to strengthen the uniqueness of the message id.
 108 \end{funcdesc}
 109
 110 \begin{funcdesc}{decode_rfc2231}{s}
 111 Decode the string \var{s} according to \rfc{2231}.
 112 \end{funcdesc}
 113
 114 \begin{funcdesc}{encode_rfc2231}{s\optional{, charset\optional{, language}}}
 115 Encode the string \var{s} according to \rfc{2231}.  Optional
 116 \var{charset} and \var{language}, if given is the character set name
 117 and language name to use.  If neither is given, \var{s} is returned
 118 as-is.  If \var{charset} is given but \var{language} is not, the
 119 string is encoded using the empty string for \var{language}.
 120 \end{funcdesc}
 121
 122 \begin{funcdesc}{decode_params}{params}
 123 Decode parameters list according to \rfc{2231}.  \var{params} is a
 124 sequence of 2-tuples containing elements of the form
 125 \code{(content-type, string-value)}.
 126 \end{funcdesc}
 127
 128 The following functions have been deprecated:
 129
 130 \begin{funcdesc}{dump_address_pair}{pair}
 131 \deprecated{2.2.2}{Use \function{formataddr()} instead.}
 132 \end{funcdesc}
 133
 134 \begin{funcdesc}{decode}{s}
 135 \deprecated{2.2.2}{Use \method{Header.decode_header()} instead.}
 136 \end{funcdesc}
 137
 138
 139 \begin{funcdesc}{encode}{s\optional{, charset\optional{, encoding}}}
 140 \deprecated{2.2.2}{Use \method{Header.encode()} instead.}
 141 \end{funcdesc}
 142