Debian Codegraph @

Doc/library/email.utils.rst

raw
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
11 There are a couple of useful utilities provided in the :mod:`email.utils`
12 module:
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
42 The remaining functions are part of the legacy (``Compat32``) email API. There
43 is no need to directly use these with the new API, since the parsing and
44 formatting they provide is done automatically by the header parsing machinery
45 of 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`.