1:mod:`!email.utils`: Miscellaneous utilities 2-------------------------------------------- 3 4.. module:: email.utils 5 :synopsis: Miscellaneous email package utilities. 6 7**Source code:** :source:`Lib/email/utils.py` 8 9-------------- 10 11There are a couple of useful utilities provided in the :mod:`email.utils` 12module: 13 14.. function:: localtime(dt=None) 15 16 Return local time as an aware datetime object. If called without 17 arguments, return current time. Otherwise *dt* argument should be a 18 :class:`~datetime.datetime` instance, and it is converted to the local time 19 zone according to the system time zone database. If *dt* is naive (that 20 is, ``dt.tzinfo`` is ``None``), it is assumed to be in local time. The 21 *isdst* parameter is ignored. 22 23 .. versionadded:: 3.3 24 25 .. deprecated-removed:: 3.12 3.14 26 The *isdst* parameter. 27 28.. function:: make_msgid(idstring=None, domain=None) 29 30 Returns a string suitable for an :rfc:`2822`\ -compliant 31 :mailheader:`Message-ID` header. Optional *idstring* if given, is a string 32 used to strengthen the uniqueness of the message id. Optional *domain* if 33 given provides the portion of the msgid after the '@'. The default is the 34 local hostname. It is not normally necessary to override this default, but 35 may be useful certain cases, such as a constructing distributed system that 36 uses a consistent domain name across multiple hosts. 37 38 .. versionchanged:: 3.2 39 Added the *domain* keyword. 40 41 42The remaining functions are part of the legacy (``Compat32``) email API. There 43is no need to directly use these with the new API, since the parsing and 44formatting they provide is done automatically by the header parsing machinery 45of the new API. 46 47 48.. function:: quote(str) 49 50 Return a new string with backslashes in *str* replaced by two backslashes, and 51 double quotes replaced by backslash-double quote. 52 53 54.. function:: unquote(str) 55 56 Return a new string which is an *unquoted* version of *str*. If *str* ends and 57 begins with double quotes, they are stripped off. Likewise if *str* ends and 58 begins with angle brackets, they are stripped off. 59 60 61.. function:: parseaddr(address, *, strict=True) 62 63 Parse address -- which should be the value of some address-containing field such 64 as :mailheader:`To` or :mailheader:`Cc` -- into its constituent *realname* and 65 *email address* parts. Returns a tuple of that information, unless the parse 66 fails, in which case a 2-tuple of ``('', '')`` is returned. 67 68 If *strict* is true, use a strict parser which rejects malformed inputs. 69 70 .. versionchanged:: 3.13 71 Add *strict* optional parameter and reject malformed inputs by default. 72 73 74.. function:: formataddr(pair, charset='utf-8') 75 76 The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname, 77 email_address)`` and returns the string value suitable for a :mailheader:`To` or 78 :mailheader:`Cc` header. If the first element of *pair* is false, then the 79 second element is returned unmodified. 80 81 Optional *charset* is the character set that will be used in the :rfc:`2047` 82 encoding of the ``realname`` if the ``realname`` contains non-ASCII 83 characters. Can be an instance of :class:`str` or a 84 :class:`~email.charset.Charset`. Defaults to ``utf-8``. 85 86 .. versionchanged:: 3.3 87 Added the *charset* option. 88 89 90.. function:: getaddresses(fieldvalues, *, strict=True) 91 92 This method returns a list of 2-tuples of the form returned by ``parseaddr()``. 93 *fieldvalues* is a sequence of header field values as might be returned by 94 :meth:`Message.get_all <email.message.Message.get_all>`. 95 96 If *strict* is true, use a strict parser which rejects malformed inputs. 97 98 Here's a simple example that gets all the recipients of a message:: 99 100 from email.utils import getaddresses 101 102 tos = msg.get_all('to', []) 103 ccs = msg.get_all('cc', []) 104 resent_tos = msg.get_all('resent-to', []) 105 resent_ccs = msg.get_all('resent-cc', []) 106 all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs) 107 108 .. versionchanged:: 3.13 109 Add *strict* optional parameter and reject malformed inputs by default. 110 111 112.. function:: parsedate(date) 113 114 Attempts to parse a date according to the rules in :rfc:`2822`. however, some 115 mailers don't follow that format as specified, so :func:`parsedate` tries to 116 guess correctly in such cases. *date* is a string containing an :rfc:`2822` 117 date, such as ``"Mon, 20 Nov 1995 19:12:08 -0500"``. If it succeeds in parsing 118 the date, :func:`parsedate` returns a 9-tuple that can be passed directly to 119 :func:`time.mktime`; otherwise ``None`` will be returned. Note that indexes 6, 120 7, and 8 of the result tuple are not usable. 121 122 123.. function:: parsedate_tz(date) 124 125 Performs the same function as :func:`parsedate`, but returns either ``None`` or 126 a 10-tuple; the first 9 elements make up a tuple that can be passed directly to 127 :func:`time.mktime`, and the tenth is the offset of the date's timezone from UTC 128 (which is the official term for Greenwich Mean Time) [#]_. If the input string 129 has no timezone, the last element of the tuple returned is ``0``, which represents 130 UTC. Note that indexes 6, 7, and 8 of the result tuple are not usable. 131 132 133.. function:: parsedate_to_datetime(date) 134 135 The inverse of :func:`format_datetime`. Performs the same function as 136 :func:`parsedate`, but on success returns a :mod:`~datetime.datetime`; 137 otherwise ``ValueError`` is raised if *date* contains an invalid value such 138 as an hour greater than 23 or a timezone offset not between -24 and 24 hours. 139 If the input date has a timezone of ``-0000``, the ``datetime`` will be a naive 140 ``datetime``, and if the date is conforming to the RFCs it will represent a 141 time in UTC but with no indication of the actual source timezone of the 142 message the date comes from. If the input date has any other valid timezone 143 offset, the ``datetime`` will be an aware ``datetime`` with the 144 corresponding a :class:`~datetime.timezone` :class:`~datetime.tzinfo`. 145 146 .. versionadded:: 3.3 147 148 149.. function:: mktime_tz(tuple) 150 151 Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC 152 timestamp (seconds since the Epoch). If the timezone item in the 153 tuple is ``None``, assume local time. 154 155 156.. function:: formatdate(timeval=None, localtime=False, usegmt=False) 157 158 Returns a date string as per :rfc:`2822`, e.g.:: 159 160 Fri, 09 Nov 2001 01:08:47 -0000 161 162 Optional *timeval* if given is a floating-point time value as accepted by 163 :func:`time.gmtime` and :func:`time.localtime`, otherwise the current time is 164 used. 165 166 Optional *localtime* is a flag that when ``True``, interprets *timeval*, and 167 returns a date relative to the local timezone instead of UTC, properly taking 168 daylight savings time into account. The default is ``False`` meaning UTC is 169 used. 170 171 Optional *usegmt* is a flag that when ``True``, outputs a date string with the 172 timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. This is 173 needed for some protocols (such as HTTP). This only applies when *localtime* is 174 ``False``. The default is ``False``. 175 176 177.. function:: format_datetime(dt, usegmt=False) 178 179 Like ``formatdate``, but the input is a :mod:`datetime` instance. If it is 180 a naive datetime, it is assumed to be "UTC with no information about the 181 source timezone", and the conventional ``-0000`` is used for the timezone. 182 If it is an aware ``datetime``, then the numeric timezone offset is used. 183 If it is an aware timezone with offset zero, then *usegmt* may be set to 184 ``True``, in which case the string ``GMT`` is used instead of the numeric 185 timezone offset. This provides a way to generate standards conformant HTTP 186 date headers. 187 188 .. versionadded:: 3.3 189 190 191.. function:: decode_rfc2231(s) 192 193 Decode the string *s* according to :rfc:`2231`. 194 195 196.. function:: encode_rfc2231(s, charset=None, language=None) 197 198 Encode the string *s* according to :rfc:`2231`. Optional *charset* and 199 *language*, if given is the character set name and language name to use. If 200 neither is given, *s* is returned as-is. If *charset* is given but *language* 201 is not, the string is encoded using the empty string for *language*. 202 203 204.. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii') 205 206 When a header parameter is encoded in :rfc:`2231` format, 207 :meth:`Message.get_param <email.message.Message.get_param>` may return a 208 3-tuple containing the character set, 209 language, and value. :func:`collapse_rfc2231_value` turns this into a unicode 210 string. Optional *errors* is passed to the *errors* argument of :class:`str`'s 211 :func:`~str.encode` method; it defaults to ``'replace'``. Optional 212 *fallback_charset* specifies the character set to use if the one in the 213 :rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``. 214 215 For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is not 216 a tuple, it should be a string and it is returned unquoted. 217 218 219.. function:: decode_params(params) 220 221 Decode parameters list according to :rfc:`2231`. *params* is a sequence of 222 2-tuples containing elements of the form ``(content-type, string-value)``. 223 224 225.. rubric:: Footnotes 226 227.. [#] Note that the sign of the timezone offset is the opposite of the sign of the 228 ``time.timezone`` variable for the same timezone; the latter variable follows 229 the POSIX standard while this module follows :rfc:`2822`. 230