1 :mod:`email.utils`: Miscellaneous utilities 2 ------------------------------------------- 3 4 .. module:: email.utils 5 :synopsis: Miscellaneous email package utilities. 6 7 8 There are several useful utilities provided in the :mod:`email.utils` module: 9 10 11 .. function:: quote(str) 12 13 Return a new string with backslashes in *str* replaced by two backslashes, and 14 double quotes replaced by backslash-double quote. 15 16 17 .. function:: unquote(str) 18 19 Return a new string which is an *unquoted* version of *str*. If *str* ends and 20 begins with double quotes, they are stripped off. Likewise if *str* ends and 21 begins with angle brackets, they are stripped off. 22 23 24 .. function:: parseaddr(address) 25 26 Parse address -- which should be the value of some address-containing field such 27 as :mailheader:`To` or :mailheader:`Cc` -- into its constituent *realname* and 28 *email address* parts. Returns a tuple of that information, unless the parse 29 fails, in which case a 2-tuple of ``('', '')`` is returned. 30 31 32 .. function:: formataddr(pair) 33 34 The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname, 35 email_address)`` and returns the string value suitable for a :mailheader:`To` or 36 :mailheader:`Cc` header. If the first element of *pair* is false, then the 37 second element is returned unmodified. 38 39 40 .. function:: getaddresses(fieldvalues) 41 42 This method returns a list of 2-tuples of the form returned by ``parseaddr()``. 43 *fieldvalues* is a sequence of header field values as might be returned by 44 :meth:`Message.get_all <email.message.Message.get_all>`. Here's a simple 45 example that gets all the recipients of a message:: 46 47 from email.utils import getaddresses 48 49 tos = msg.get_all('to', []) 50 ccs = msg.get_all('cc', []) 51 resent_tos = msg.get_all('resent-to', []) 52 resent_ccs = msg.get_all('resent-cc', []) 53 all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs) 54 55 56 .. function:: parsedate(date) 57 58 Attempts to parse a date according to the rules in :rfc:`2822`. however, some 59 mailers don't follow that format as specified, so :func:`parsedate` tries to 60 guess correctly in such cases. *date* is a string containing an :rfc:`2822` 61 date, such as ``"Mon, 20 Nov 1995 19:12:08 -0500"``. If it succeeds in parsing 62 the date, :func:`parsedate` returns a 9-tuple that can be passed directly to 63 :func:`time.mktime`; otherwise ``None`` will be returned. Note that indexes 6, 64 7, and 8 of the result tuple are not usable. 65 66 67 .. function:: parsedate_tz(date) 68 69 Performs the same function as :func:`parsedate`, but returns either ``None`` or 70 a 10-tuple; the first 9 elements make up a tuple that can be passed directly to 71 :func:`time.mktime`, and the tenth is the offset of the date's timezone from UTC 72 (which is the official term for Greenwich Mean Time) [#]_. If the input string 73 has no timezone, the last element of the tuple returned is ``None``. Note that 74 indexes 6, 7, and 8 of the result tuple are not usable. 75 76 77 .. function:: mktime_tz(tuple) 78 79 Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC 80 timestamp (seconds since the Epoch). If the timezone item in the 81 tuple is ``None``, assume local time. 82 83 84 .. function:: formatdate([timeval[, localtime][, usegmt]]) 85 86 Returns a date string as per :rfc:`2822`, e.g.:: 87 88 Fri, 09 Nov 2001 01:08:47 -0000 89 90 Optional *timeval* if given is a floating point time value as accepted by 91 :func:`time.gmtime` and :func:`time.localtime`, otherwise the current time is 92 used. 93 94 Optional *localtime* is a flag that when ``True``, interprets *timeval*, and 95 returns a date relative to the local timezone instead of UTC, properly taking 96 daylight savings time into account. The default is ``False`` meaning UTC is 97 used. 98 99 Optional *usegmt* is a flag that when ``True``, outputs a date string with the 100 timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. This is 101 needed for some protocols (such as HTTP). This only applies when *localtime* is 102 ``False``. The default is ``False``. 103 104 .. versionadded:: 2.4 105 106 107 .. function:: make_msgid([idstring]) 108 109 Returns a string suitable for an :rfc:`2822`\ -compliant 110 :mailheader:`Message-ID` header. Optional *idstring* if given, is a string used 111 to strengthen the uniqueness of the message id. 112 113 114 .. function:: decode_rfc2231(s) 115 116 Decode the string *s* according to :rfc:`2231`. 117 118 119 .. function:: encode_rfc2231(s[, charset[, language]]) 120 121 Encode the string *s* according to :rfc:`2231`. Optional *charset* and 122 *language*, if given is the character set name and language name to use. If 123 neither is given, *s* is returned as-is. If *charset* is given but *language* 124 is not, the string is encoded using the empty string for *language*. 125 126 127 .. function:: collapse_rfc2231_value(value[, errors[, fallback_charset]]) 128 129 When a header parameter is encoded in :rfc:`2231` format, 130 :meth:`Message.get_param <email.message.Message.get_param>` may return a 131 3-tuple containing the character set, 132 language, and value. :func:`collapse_rfc2231_value` turns this into a unicode 133 string. Optional *errors* is passed to the *errors* argument of the built-in 134 :func:`unicode` function; it defaults to ``replace``. Optional 135 *fallback_charset* specifies the character set to use if the one in the 136 :rfc:`2231` header is not known by Python; it defaults to ``us-ascii``. 137 138 For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is not 139 a tuple, it should be a string and it is returned unquoted. 140 141 142 .. function:: decode_params(params) 143 144 Decode parameters list according to :rfc:`2231`. *params* is a sequence of 145 2-tuples containing elements of the form ``(content-type, string-value)``. 146 147 .. versionchanged:: 2.4 148 The :func:`dump_address_pair` function has been removed; use :func:`formataddr` 149 instead. 150 151 .. versionchanged:: 2.4 152 The :func:`decode` function has been removed; use the 153 :meth:`Header.decode_header <email.header.Header.decode_header>` method 154 instead. 155 156 .. versionchanged:: 2.4 157 The :func:`encode` function has been removed; use the :meth:`Header.encode 158 <email.header.Header.encode>` method instead. 159 160 .. rubric:: Footnotes 161 162 .. [#] Note that the sign of the timezone offset is the opposite of the sign of the 163 ``time.timezone`` variable for the same timezone; the latter variable follows 164 the POSIX standard while this module follows :rfc:`2822`. 165
