Debian Codegraph @

Lib/email/utils.py

raw
1 # Copyright (C) 2001 Python Software Foundation
2 # Author: Barry Warsaw
3 # Contact: [email protected]
4
5 """Miscellaneous utilities."""
6
7 __all__ = [
8 'collapse_rfc2231_value',
9 'decode_params',
10 'decode_rfc2231',
11 'encode_rfc2231',
12 'formataddr',
13 'formatdate',
14 'format_datetime',
15 'getaddresses',
16 'make_msgid',
17 'mktime_tz',
18 'parseaddr',
19 'parsedate',
20 'parsedate_tz',
21 'parsedate_to_datetime',
22 'unquote',
23 ]
24
25 import os
26 import re
27 import time
28 import datetime
29 import urllib.parse
30
31 from email._parseaddr import quote
32 from email._parseaddr import AddressList as _AddressList
33 from email._parseaddr import mktime_tz
34
35 from email._parseaddr import parsedate, parsedate_tz, _parsedate_tz
36
37 COMMASPACE = ', '
38 EMPTYSTRING = ''
39 UEMPTYSTRING = ''
40 CRLF = '\r\n'
41 TICK = "'"
42
43 specialsre = re.compile(r'[][\\()<>@,:;".]')
44 escapesre = re.compile(r'[\\"]')
45
46
47 def _has_surrogates(s):
48 """Return True if s may contain surrogate-escaped binary data."""
49 # This check is based on the fact that unless there are surrogates, utf8
50 # (Python's default encoding) can encode any string. This is the fastest
51 # way to check for surrogates, see bpo-11454 (moved to gh-55663) for timings.
52 try:
53 s.encode()
54 return False
55 except UnicodeEncodeError:
56 return True
57
58 # How to deal with a string containing bytes before handing it to the
59 # application through the 'normal' interface.
60 def _sanitize(string):
61 # Turn any escaped bytes into unicode 'unknown' char. If the escaped
62 # bytes happen to be utf-8 they will instead get decoded, even if they
63 # were invalid in the charset the source was supposed to be in. This
64 # seems like it is not a bad thing; a defect was still registered.
65 original_bytes = string.encode('utf-8', 'surrogateescape')
66 return original_bytes.decode('utf-8', 'replace')
67
68
69
70 # Helpers
71
72 def formataddr(pair, charset='utf-8'):
73 """The inverse of parseaddr(), this takes a 2-tuple of the form
74 (realname, email_address) and returns the string value suitable
75 for an RFC 2822 From, To or Cc header.
76
77 If the first element of pair is false, then the second element is
78 returned unmodified.
79
80 The optional charset is the character set that is used to encode
81 realname in case realname is not ASCII safe. Can be an instance of str or
82 a Charset-like object which has a header_encode method. Default is
83 'utf-8'.
84 """
85 name, address = pair
86 # The address MUST (per RFC) be ascii, so raise a UnicodeError if it isn't.
87 address.encode('ascii')
88 if name:
89 try:
90 name.encode('ascii')
91 except UnicodeEncodeError:
92 if isinstance(charset, str):
93 # lazy import to improve module import time
94 from email.charset import Charset
95 charset = Charset(charset)
96 encoded_name = charset.header_encode(name)
97 return "%s <%s>" % (encoded_name, address)
98 else:
99 quotes = ''
100 if specialsre.search(name):
101 quotes = '"'
102 name = escapesre.sub(r'\\\g<0>', name)
103 return '%s%s%s <%s>' % (quotes, name, quotes, address)
104 return address
105
106
107 def _iter_escaped_chars(addr):
108 pos = 0
109 escape = False
110 for pos, ch in enumerate(addr):
111 if escape:
112 yield (pos, '\\' + ch)
113 escape = False
114 elif ch == '\\':
115 escape = True
116 else:
117 yield (pos, ch)
118 if escape:
119 yield (pos, '\\')
120
121
122 def _strip_quoted_realnames(addr):
123 """Strip real names between quotes."""
124 if '"' not in addr:
125 # Fast path
126 return addr
127
128 start = 0
129 open_pos = None
130 result = []
131 for pos, ch in _iter_escaped_chars(addr):
132 if ch == '"':
133 if open_pos is None:
134 open_pos = pos
135 else:
136 if start != open_pos:
137 result.append(addr[start:open_pos])
138 start = pos + 1
139 open_pos = None
140
141 if start < len(addr):
142 result.append(addr[start:])
143
144 return ''.join(result)
145
146
147 supports_strict_parsing = True
148
149 def getaddresses(fieldvalues, *, strict=True):
150 """Return a list of (REALNAME, EMAIL) or ('','') for each fieldvalue.
151
152 When parsing fails for a fieldvalue, a 2-tuple of ('', '') is returned in
153 its place.
154
155 If strict is true, use a strict parser which rejects malformed inputs.
156 """
157
158 # If strict is true, if the resulting list of parsed addresses is greater
159 # than the number of fieldvalues in the input list, a parsing error has
160 # occurred and consequently a list containing a single empty 2-tuple [('',
161 # '')] is returned in its place. This is done to avoid invalid output.
162 #
163 # Malformed input: getaddresses(['[email protected] <[email protected]>'])
164 # Invalid output: [('', '[email protected]'), ('', '[email protected]')]
165 # Safe output: [('', '')]
166
167 if not strict:
168 all = COMMASPACE.join(str(v) for v in fieldvalues)
169 a = _AddressList(all)
170 return a.addresslist
171
172 fieldvalues = [str(v) for v in fieldvalues]
173 fieldvalues = _pre_parse_validation(fieldvalues)
174 addr = COMMASPACE.join(fieldvalues)
175 a = _AddressList(addr)
176 result = _post_parse_validation(a.addresslist)
177
178 # Treat output as invalid if the number of addresses is not equal to the
179 # expected number of addresses.
180 n = 0
181 for v in fieldvalues:
182 # When a comma is used in the Real Name part it is not a deliminator.
183 # So strip those out before counting the commas.
184 v = _strip_quoted_realnames(v)
185 # Expected number of addresses: 1 + number of commas
186 n += 1 + v.count(',')
187 if len(result) != n:
188 return [('', '')]
189
190 return result
191
192
193 def _check_parenthesis(addr):
194 # Ignore parenthesis in quoted real names.
195 addr = _strip_quoted_realnames(addr)
196
197 opens = 0
198 for pos, ch in _iter_escaped_chars(addr):
199 if ch == '(':
200 opens += 1
201 elif ch == ')':
202 opens -= 1
203 if opens < 0:
204 return False
205 return (opens == 0)
206
207
208 def _pre_parse_validation(email_header_fields):
209 accepted_values = []
210 for v in email_header_fields:
211 if not _check_parenthesis(v):
212 v = "('', '')"
213 accepted_values.append(v)
214
215 return accepted_values
216
217
218 def _post_parse_validation(parsed_email_header_tuples):
219 accepted_values = []
220 # The parser would have parsed a correctly formatted domain-literal
221 # The existence of an [ after parsing indicates a parsing failure
222 for v in parsed_email_header_tuples:
223 if '[' in v[1]:
224 v = ('', '')
225 accepted_values.append(v)
226
227 return accepted_values
228
229
230 def _format_timetuple_and_zone(timetuple, zone):
231 return '%s, %02d %s %04d %02d:%02d:%02d %s' % (
232 ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'][timetuple[6]],
233 timetuple[2],
234 ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
235 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][timetuple[1] - 1],
236 timetuple[0], timetuple[3], timetuple[4], timetuple[5],
237 zone)
238
239 def formatdate(timeval=None, localtime=False, usegmt=False):
240 """Returns a date string as specified by RFC 2822, e.g.:
241
242 Fri, 09 Nov 2001 01:08:47 -0000
243
244 Optional timeval if given is a floating-point time value as accepted by
245 gmtime() and localtime(), otherwise the current time is used.
246
247 Optional localtime is a flag that when True, interprets timeval, and
248 returns a date relative to the local timezone instead of UTC, properly
249 taking daylight savings time into account.
250
251 Optional argument usegmt means that the timezone is written out as
252 an ascii string, not numeric one (so "GMT" instead of "+0000"). This
253 is needed for HTTP, and is only used when localtime==False.
254 """
255 # Note: we cannot use strftime() because that honors the locale and RFC
256 # 2822 requires that day and month names be the English abbreviations.
257 if timeval is None:
258 timeval = time.time()
259 dt = datetime.datetime.fromtimestamp(timeval, datetime.timezone.utc)
260
261 if localtime:
262 dt = dt.astimezone()
263 usegmt = False
264 elif not usegmt:
265 dt = dt.replace(tzinfo=None)
266 return format_datetime(dt, usegmt)
267
268 def format_datetime(dt, usegmt=False):
269 """Turn a datetime into a date string as specified in RFC 2822.
270
271 If usegmt is True, dt must be an aware datetime with an offset of zero. In
272 this case 'GMT' will be rendered instead of the normal +0000 required by
273 RFC2822. This is to support HTTP headers involving date stamps.
274 """
275 now = dt.timetuple()
276 if usegmt:
277 if dt.tzinfo is None or dt.tzinfo != datetime.timezone.utc:
278 raise ValueError("usegmt option requires a UTC datetime")
279 zone = 'GMT'
280 elif dt.tzinfo is None:
281 zone = '-0000'
282 else:
283 zone = dt.strftime("%z")
284 return _format_timetuple_and_zone(now, zone)
285
286
287 def make_msgid(idstring=None, domain=None):
288 """Returns a string suitable for RFC 2822 compliant Message-ID, e.g:
289
290 <142480216486.20800.16526388040877946887@nightshade.la.mastaler.com>
291
292 Optional idstring if given is a string used to strengthen the
293 uniqueness of the message id. Optional domain if given provides the
294 portion of the message id after the '@'. It defaults to the locally
295 defined hostname.
296 """
297 # Lazy imports to speedup module import time
298 # (no other functions in email.utils need these modules)
299 import random
300 import socket
301
302 timeval = int(time.time()*100)
303 pid = os.getpid()
304 randint = random.getrandbits(64)
305 if idstring is None:
306 idstring = ''
307 else:
308 idstring = '.' + idstring
309 if domain is None:
310 domain = socket.getfqdn()
311 msgid = '<%d.%d.%d%s@%s>' % (timeval, pid, randint, idstring, domain)
312 return msgid
313
314
315 def parsedate_to_datetime(data):
316 parsed_date_tz = _parsedate_tz(data)
317 if parsed_date_tz is None:
318 raise ValueError('Invalid date value or format "%s"' % str(data))
319 *dtuple, tz = parsed_date_tz
320 if tz is None:
321 return datetime.datetime(*dtuple[:6])
322 return datetime.datetime(*dtuple[:6],
323 tzinfo=datetime.timezone(datetime.timedelta(seconds=tz)))
324
325
326 def parseaddr(addr, *, strict=True):
327 """
328 Parse addr into its constituent realname and email address parts.
329
330 Return a tuple of realname and email address, unless the parse fails, in
331 which case return a 2-tuple of ('', '').
332
333 If strict is True, use a strict parser which rejects malformed inputs.
334 """
335 if not strict:
336 addrs = _AddressList(addr).addresslist
337 if not addrs:
338 return ('', '')
339 return addrs[0]
340
341 if isinstance(addr, list):
342 addr = addr[0]
343
344 if not isinstance(addr, str):
345 return ('', '')
346
347 addr = _pre_parse_validation([addr])[0]
348 addrs = _post_parse_validation(_AddressList(addr).addresslist)
349
350 if not addrs or len(addrs) > 1:
351 return ('', '')
352
353 return addrs[0]
354
355
356 # rfc822.unquote() doesn't properly de-backslash-ify in Python pre-2.3.
357 def unquote(str):
358 """Remove quotes from a string."""
359 if len(str) > 1:
360 if str.startswith('"') and str.endswith('"'):
361 return str[1:-1].replace('\\\\', '\\').replace('\\"', '"')
362 if str.startswith('<') and str.endswith('>'):
363 return str[1:-1]
364 return str
365
366
367
368 # RFC2231-related functions - parameter encoding and decoding
369 def decode_rfc2231(s):
370 """Decode string according to RFC 2231"""
371 parts = s.split(TICK, 2)
372 if len(parts) <= 2:
373 return None, None, s
374 return parts
375
376
377 def encode_rfc2231(s, charset=None, language=None):
378 """Encode string according to RFC 2231.
379
380 If neither charset nor language is given, then s is returned as-is. If
381 charset is given but not language, the string is encoded using the empty
382 string for language.
383 """
384 s = urllib.parse.quote(s, safe='', encoding=charset or 'ascii')
385 if charset is None and language is None:
386 return s
387 if language is None:
388 language = ''
389 return "%s'%s'%s" % (charset, language, s)
390
391
392 rfc2231_continuation = re.compile(r'^(?P<name>\w+)\*((?P<num>[0-9]+)\*?)?$',
393 re.ASCII)
394
395 def decode_params(params):
396 """Decode parameters list according to RFC 2231.
397
398 params is a sequence of 2-tuples containing (param name, string value).
399 """
400 new_params = [params[0]]
401 # Map parameter's name to a list of continuations. The values are a
402 # 3-tuple of the continuation number, the string value, and a flag
403 # specifying whether a particular segment is %-encoded.
404 rfc2231_params = {}
405 for name, value in params[1:]:
406 encoded = name.endswith('*')
407 value = unquote(value)
408 mo = rfc2231_continuation.match(name)
409 if mo:
410 name, num = mo.group('name', 'num')
411 if num is not None:
412 num = int(num)
413 rfc2231_params.setdefault(name, []).append((num, value, encoded))
414 else:
415 new_params.append((name, '"%s"' % quote(value)))
416 if rfc2231_params:
417 for name, continuations in rfc2231_params.items():
418 value = []
419 extended = False
420 # Sort by number, treating None as 0 if there is no 0,
421 # and ignore it if there is already a 0.
422 has_zero = any(x[0] == 0 for x in continuations)
423 if has_zero:
424 continuations = [x for x in continuations if x[0] is not None]
425 else:
426 continuations = [(x[0] or 0, x[1], x[2]) for x in continuations]
427 continuations.sort(key=lambda x: x[0])
428 # And now append all values in numerical order, converting
429 # %-encodings for the encoded segments. If any of the
430 # continuation names ends in a *, then the entire string, after
431 # decoding segments and concatenating, must have the charset and
432 # language specifiers at the beginning of the string.
433 for num, s, encoded in continuations:
434 if encoded:
435 # Decode as "latin-1", so the characters in s directly
436 # represent the percent-encoded octet values.
437 # collapse_rfc2231_value treats this as an octet sequence.
438 s = urllib.parse.unquote(s, encoding="latin-1")
439 extended = True
440 value.append(s)
441 value = quote(EMPTYSTRING.join(value))
442 if extended:
443 charset, language, value = decode_rfc2231(value)
444 new_params.append((name, (charset, language, '"%s"' % value)))
445 else:
446 new_params.append((name, '"%s"' % value))
447 return new_params
448
449 def collapse_rfc2231_value(value, errors='replace',
450 fallback_charset='us-ascii'):
451 if not isinstance(value, tuple) or len(value) != 3:
452 return unquote(value)
453 # While value comes to us as a unicode string, we need it to be a bytes
454 # object. We do not want bytes() normal utf-8 decoder, we want a straight
455 # interpretation of the string as character bytes.
456 charset, language, text = value
457 if charset is None:
458 # Issue 17369: if charset/lang is None, decode_rfc2231 couldn't parse
459 # the value, so use the fallback_charset.
460 charset = fallback_charset
461 rawbytes = bytes(text, 'raw-unicode-escape')
462 try:
463 return str(rawbytes, charset, errors)
464 except LookupError:
465 # charset is not a known codec.
466 return unquote(text)
467
468
469 #
470 # datetime doesn't provide a localtime function yet, so provide one. Code
471 # adapted from the patch in issue 9527. This may not be perfect, but it is
472 # better than not having it.
473 #
474
475 def localtime(dt=None):
476 """Return local time as an aware datetime object.
477
478 If called without arguments, return current time. Otherwise *dt*
479 argument should be a datetime instance, and it is converted to the
480 local time zone according to the system time zone database. If *dt* is
481 naive (that is, dt.tzinfo is None), it is assumed to be in local time.
482
483 """
484 if dt is None:
485 dt = datetime.datetime.now()
486 return dt.astimezone()