1 # Copyright (C) 2001-2010 Python Software Foundation 2 # Author: Barry Warsaw 3 # Contact: email-sig (at] python.org 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 'getaddresses', 15 'make_msgid', 16 'mktime_tz', 17 'parseaddr', 18 'parsedate', 19 'parsedate_tz', 20 'unquote', 21 ] 22 23 import os 24 import re 25 import time 26 import base64 27 import random 28 import socket 29 import urllib 30 import warnings 31 32 from email._parseaddr import quote 33 from email._parseaddr import AddressList as _AddressList 34 from email._parseaddr import mktime_tz 35 36 # We need wormarounds for bugs in these methods in older Pythons (see below) 37 from email._parseaddr import parsedate as _parsedate 38 from email._parseaddr import parsedate_tz as _parsedate_tz 39 40 from quopri import decodestring as _qdecode 41 42 # Intrapackage imports 43 from email.encoders import _bencode, _qencode 44 45 COMMASPACE = ', ' 46 EMPTYSTRING = '' 47 UEMPTYSTRING = u'' 48 CRLF = '\r\n' 49 TICK = "'" 50 51 specialsre = re.compile(r'[][\\()<>@,:;".]') 52 escapesre = re.compile(r'[][\\()"]') 53 54 55 57 # Helpers 58 59 def _identity(s): 60 return s 61 62 63 def _bdecode(s): 64 """Decodes a base64 string. 65 66 This function is equivalent to base64.decodestring and it's retained only 67 for backward compatibility. It used to remove the last \\n of the decoded 68 string, if it had any (see issue 7143). 69 """ 70 if not s: 71 return s 72 return base64.decodestring(s) 73 74 75 77 def fix_eols(s): 78 """Replace all line-ending characters with \\r\\n.""" 79 # Fix newlines with no preceding carriage return 80 s = re.sub(r'(?<!\r)\n', CRLF, s) 81 # Fix carriage returns with no following newline 82 s = re.sub(r'\r(?!\n)', CRLF, s) 83 return s 84 85 86 88 def formataddr(pair): 89 """The inverse of parseaddr(), this takes a 2-tuple of the form 90 (realname, email_address) and returns the string value suitable 91 for an RFC 2822 From, To or Cc header. 92 93 If the first element of pair is false, then the second element is 94 returned unmodified. 95 """ 96 name, address = pair 97 if name: 98 quotes = '' 99 if specialsre.search(name): 100 quotes = '"' 101 name = escapesre.sub(r'\\\g<0>', name) 102 return '%s%s%s <%s>' % (quotes, name, quotes, address) 103 return address 104 105 106 108 def getaddresses(fieldvalues): 109 """Return a list of (REALNAME, EMAIL) for each fieldvalue.""" 110 all = COMMASPACE.join(fieldvalues) 111 a = _AddressList(all) 112 return a.addresslist 113 114 115 117 ecre = re.compile(r''' 118 =\? # literal =? 119 (?P<charset>[^?]*?) # non-greedy up to the next ? is the charset 120 \? # literal ? 121 (?P<encoding>[qb]) # either a "q" or a "b", case insensitive 122 \? # literal ? 123 (?P<atom>.*?) # non-greedy up to the next ?= is the atom 124 \?= # literal ?= 125 ''', re.VERBOSE | re.IGNORECASE) 126 127 128 130 def formatdate(timeval=None, localtime=False, usegmt=False): 131 """Returns a date string as specified by RFC 2822, e.g.: 132 133 Fri, 09 Nov 2001 01:08:47 -0000 134 135 Optional timeval if given is a floating point time value as accepted by 136 gmtime() and localtime(), otherwise the current time is used. 137 138 Optional localtime is a flag that when True, interprets timeval, and 139 returns a date relative to the local timezone instead of UTC, properly 140 taking daylight savings time into account. 141 142 Optional argument usegmt means that the timezone is written out as 143 an ascii string, not numeric one (so "GMT" instead of "+0000"). This 144 is needed for HTTP, and is only used when localtime==False. 145 """ 146 # Note: we cannot use strftime() because that honors the locale and RFC 147 # 2822 requires that day and month names be the English abbreviations. 148 if timeval is None: 149 timeval = time.time() 150 if localtime: 151 now = time.localtime(timeval) 152 # Calculate timezone offset, based on whether the local zone has 153 # daylight savings time, and whether DST is in effect. 154 if time.daylight and now[-1]: 155 offset = time.altzone 156 else: 157 offset = time.timezone 158 hours, minutes = divmod(abs(offset), 3600) 159 # Remember offset is in seconds west of UTC, but the timezone is in 160 # minutes east of UTC, so the signs differ. 161 if offset > 0: 162 sign = '-' 163 else: 164 sign = '+' 165 zone = '%s%02d%02d' % (sign, hours, minutes // 60) 166 else: 167 now = time.gmtime(timeval) 168 # Timezone offset is always -0000 169 if usegmt: 170 zone = 'GMT' 171 else: 172 zone = '-0000' 173 return '%s, %02d %s %04d %02d:%02d:%02d %s' % ( 174 ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'][now[6]], 175 now[2], 176 ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 177 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][now[1] - 1], 178 now[0], now[3], now[4], now[5], 179 zone) 180 181 182 184 def make_msgid(idstring=None): 185 """Returns a string suitable for RFC 2822 compliant Message-ID, e.g: 186 187 <20020201195627.33539.96671 (at] nightshade.la.mastaler.com> 188 189 Optional idstring if given is a string used to strengthen the 190 uniqueness of the message id. 191 """ 192 timeval = time.time() 193 utcdate = time.strftime('%Y%m%d%H%M%S', time.gmtime(timeval)) 194 pid = os.getpid() 195 randint = random.randrange(100000) 196 if idstring is None: 197 idstring = '' 198 else: 199 idstring = '.' + idstring 200 idhost = socket.getfqdn() 201 msgid = '<%s.%s.%s%s@%s>' % (utcdate, pid, randint, idstring, idhost) 202 return msgid 203 204 205 207 # These functions are in the standalone mimelib version only because they've 208 # subsequently been fixed in the latest Python versions. We use this to worm 209 # around broken older Pythons. 210 def parsedate(data): 211 if not data: 212 return None 213 return _parsedate(data) 214 215 216 def parsedate_tz(data): 217 if not data: 218 return None 219 return _parsedate_tz(data) 220 221 222 def parseaddr(addr): 223 addrs = _AddressList(addr).addresslist 224 if not addrs: 225 return '', '' 226 return addrs[0] 227 228 229 # rfc822.unquote() doesn't properly de-backslash-ify in Python pre-2.3. 230 def unquote(str): 231 """Remove quotes from a string.""" 232 if len(str) > 1: 233 if str.startswith('"') and str.endswith('"'): 234 return str[1:-1].replace('\\\\', '\\').replace('\\"', '"') 235 if str.startswith('<') and str.endswith('>'): 236 return str[1:-1] 237 return str 238 239 240 242 # RFC2231-related functions - parameter encoding and decoding 243 def decode_rfc2231(s): 244 """Decode string according to RFC 2231""" 245 parts = s.split(TICK, 2) 246 if len(parts) <= 2: 247 return None, None, s 248 return parts 249 250 251 def encode_rfc2231(s, charset=None, language=None): 252 """Encode string according to RFC 2231. 253 254 If neither charset nor language is given, then s is returned as-is. If 255 charset is given but not language, the string is encoded using the empty 256 string for language. 257 """ 258 import urllib 259 s = urllib.quote(s, safe='') 260 if charset is None and language is None: 261 return s 262 if language is None: 263 language = '' 264 return "%s'%s'%s" % (charset, language, s) 265 266 267 rfc2231_continuation = re.compile(r'^(?P<name>\w+)\*((?P<num>[0-9]+)\*?)?$') 268 269 def decode_params(params): 270 """Decode parameters list according to RFC 2231. 271 272 params is a sequence of 2-tuples containing (param name, string value). 273 """ 274 # Copy params so we don't mess with the original 275 params = params[:] 276 new_params = [] 277 # Map parameter's name to a list of continuations. The values are a 278 # 3-tuple of the continuation number, the string value, and a flag 279 # specifying whether a particular segment is %-encoded. 280 rfc2231_params = {} 281 name, value = params.pop(0) 282 new_params.append((name, value)) 283 while params: 284 name, value = params.pop(0) 285 if name.endswith('*'): 286 encoded = True 287 else: 288 encoded = False 289 value = unquote(value) 290 mo = rfc2231_continuation.match(name) 291 if mo: 292 name, num = mo.group('name', 'num') 293 if num is not None: 294 num = int(num) 295 rfc2231_params.setdefault(name, []).append((num, value, encoded)) 296 else: 297 new_params.append((name, '"%s"' % quote(value))) 298 if rfc2231_params: 299 for name, continuations in rfc2231_params.items(): 300 value = [] 301 extended = False 302 # Sort by number 303 continuations.sort() 304 # And now append all values in numerical order, converting 305 # %-encodings for the encoded segments. If any of the 306 # continuation names ends in a *, then the entire string, after 307 # decoding segments and concatenating, must have the charset and 308 # language specifiers at the beginning of the string. 309 for num, s, encoded in continuations: 310 if encoded: 311 s = urllib.unquote(s) 312 extended = True 313 value.append(s) 314 value = quote(EMPTYSTRING.join(value)) 315 if extended: 316 charset, language, value = decode_rfc2231(value) 317 new_params.append((name, (charset, language, '"%s"' % value))) 318 else: 319 new_params.append((name, '"%s"' % value)) 320 return new_params 321 322 def collapse_rfc2231_value(value, errors='replace', 323 fallback_charset='us-ascii'): 324 if isinstance(value, tuple): 325 rawval = unquote(value[2]) 326 charset = value[0] or 'us-ascii' 327 try: 328 return unicode(rawval, charset, errors) 329 except LookupError: 330 # XXX charset is unknown to Python. 331 return unicode(rawval, fallback_charset, errors) 332 else: 333 return unquote(value) 334
