Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 1 | \declaremodule{standard}{email.Utils} |
| 2 | \modulesynopsis{Miscellaneous email package utilities.} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 3 | |
Barry Warsaw | 87d6fc5 | 2004-11-01 03:59:24 +0000 | [diff] [blame] | 4 | There are several useful utilities provided in the \module{email.Utils} |
| 5 | module: |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 6 | |
| 7 | \begin{funcdesc}{quote}{str} |
| 8 | Return a new string with backslashes in \var{str} replaced by two |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 9 | backslashes, and double quotes replaced by backslash-double quote. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 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 |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 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 |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 23 | information, unless the parse fails, in which case a 2-tuple of |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 24 | \code{('', '')} is returned. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 25 | \end{funcdesc} |
| 26 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 27 | \begin{funcdesc}{formataddr}{pair} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 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 |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 30 | for a \mailheader{To} or \mailheader{Cc} header. If the first element of |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 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 |
Barry Warsaw | c421ad4 | 2002-05-22 01:22:46 +0000 | [diff] [blame] | 37 | values as might be returned by \method{Message.get_all()}. Here's a |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 38 | simple example that gets all the recipients of a message: |
| 39 | |
| 40 | \begin{verbatim} |
| 41 | from email.Utils import getaddresses |
| 42 | |
Barry Warsaw | d05e051 | 2001-10-22 20:53:45 +0000 | [diff] [blame] | 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', []) |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 47 | all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs) |
| 48 | \end{verbatim} |
| 49 | \end{funcdesc} |
| 50 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 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 |
Andrew M. Kuchling | 43dc1fc | 2001-11-05 01:55:03 +0000 | [diff] [blame] | 83 | changes in daylight savings time, though not worth worrying about for |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 84 | common use. |
| 85 | \end{funcdesc} |
| 86 | |
Anthony Baxter | 3dd9e46 | 2004-10-11 13:53:08 +0000 | [diff] [blame] | 87 | \begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}\optional{, usegmt}}} |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 88 | Returns a date string as per \rfc{2822}, e.g.: |
Barry Warsaw | 3b0c82a | 2001-11-09 17:08:13 +0000 | [diff] [blame] | 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 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 98 | Optional \var{localtime} is a flag that when \code{True}, interprets |
Barry Warsaw | 3b0c82a | 2001-11-09 17:08:13 +0000 | [diff] [blame] | 99 | \var{timeval}, and returns a date relative to the local timezone |
| 100 | instead of UTC, properly taking daylight savings time into account. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 101 | The default is \code{False} meaning UTC is used. |
Anthony Baxter | 3dd9e46 | 2004-10-11 13:53:08 +0000 | [diff] [blame] | 102 | |
| 103 | Optional \var{usegmt} is a flag that when \code{True}, outputs a |
| 104 | date string with the timezone as an ascii string \code{GMT}, rather |
| 105 | than a numeric \code{-0000}. This is needed for some protocols (such |
Skip Montanaro | bbf74f9 | 2005-07-17 11:47:46 +0000 | [diff] [blame] | 106 | as HTTP). This only applies when \var{localtime} is \code{False}. |
Skip Montanaro | 7a7b350 | 2005-07-17 15:34:58 +0000 | [diff] [blame] | 107 | \versionadded{2.4} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 108 | \end{funcdesc} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 109 | |
| 110 | \begin{funcdesc}{make_msgid}{\optional{idstring}} |
| 111 | Returns a string suitable for an \rfc{2822}-compliant |
| 112 | \mailheader{Message-ID} header. Optional \var{idstring} if given, is |
| 113 | a string used to strengthen the uniqueness of the message id. |
| 114 | \end{funcdesc} |
| 115 | |
| 116 | \begin{funcdesc}{decode_rfc2231}{s} |
| 117 | Decode the string \var{s} according to \rfc{2231}. |
| 118 | \end{funcdesc} |
| 119 | |
| 120 | \begin{funcdesc}{encode_rfc2231}{s\optional{, charset\optional{, language}}} |
| 121 | Encode the string \var{s} according to \rfc{2231}. Optional |
| 122 | \var{charset} and \var{language}, if given is the character set name |
| 123 | and language name to use. If neither is given, \var{s} is returned |
| 124 | as-is. If \var{charset} is given but \var{language} is not, the |
| 125 | string is encoded using the empty string for \var{language}. |
| 126 | \end{funcdesc} |
| 127 | |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 128 | \begin{funcdesc}{collapse_rfc2231_value}{value\optional{, errors\optional{, |
| 129 | fallback_charset}}} |
| 130 | When a header parameter is encoded in \rfc{2231} format, |
| 131 | \method{Message.get_param()} may return a 3-tuple containing the character |
| 132 | set, language, and value. \function{collapse_rfc2231_value()} turns this into |
| 133 | a unicode string. Optional \var{errors} is passed to the \var{errors} |
| 134 | argument of the built-in \function{unicode()} function; it defaults to |
| 135 | \code{replace}. Optional \var{fallback_charset} specifies the character set |
| 136 | to use if the one in the \rfc{2231} header is not known by Python; it defaults |
| 137 | to \code{us-ascii}. |
| 138 | |
| 139 | For convenience, if the \var{value} passed to |
| 140 | \function{collapse_rfc2231_value()} is not a tuple, it should be a string and |
| 141 | it is returned unquoted. |
| 142 | \end{funcdesc} |
| 143 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 144 | \begin{funcdesc}{decode_params}{params} |
| 145 | Decode parameters list according to \rfc{2231}. \var{params} is a |
| 146 | sequence of 2-tuples containing elements of the form |
| 147 | \code{(content-type, string-value)}. |
| 148 | \end{funcdesc} |
| 149 | |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 150 | \versionchanged[The \function{dump_address_pair()} function has been removed; |
Georg Brandl | a635fbb | 2006-01-15 07:55:35 +0000 | [diff] [blame] | 151 | use \function{formataddr()} instead]{2.4} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 152 | |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 153 | \versionchanged[The \function{decode()} function has been removed; use the |
Georg Brandl | a635fbb | 2006-01-15 07:55:35 +0000 | [diff] [blame] | 154 | \method{Header.decode_header()} method instead]{2.4} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 155 | |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 156 | \versionchanged[The \function{encode()} function has been removed; use the |
Georg Brandl | a635fbb | 2006-01-15 07:55:35 +0000 | [diff] [blame] | 157 | \method{Header.encode()} method instead]{2.4} |