• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright (C) 2001-2010 Python Software Foundation
2# Author: Barry Warsaw
3# Contact: email-sig@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    '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
25import os
26import re
27import time
28import random
29import socket
30import datetime
31import urllib.parse
32
33from email._parseaddr import quote
34from email._parseaddr import AddressList as _AddressList
35from email._parseaddr import mktime_tz
36
37from email._parseaddr import parsedate, parsedate_tz, _parsedate_tz
38
39# Intrapackage imports
40from email.charset import Charset
41
42COMMASPACE = ', '
43EMPTYSTRING = ''
44UEMPTYSTRING = ''
45CRLF = '\r\n'
46TICK = "'"
47
48specialsre = re.compile(r'[][\\()<>@,:;".]')
49escapesre = re.compile(r'[\\"]')
50
51def _has_surrogates(s):
52    """Return True if s contains surrogate-escaped binary data."""
53    # This check is based on the fact that unless there are surrogates, utf8
54    # (Python's default encoding) can encode any string.  This is the fastest
55    # way to check for surrogates, see issue 11454 for timings.
56    try:
57        s.encode()
58        return False
59    except UnicodeEncodeError:
60        return True
61
62# How to deal with a string containing bytes before handing it to the
63# application through the 'normal' interface.
64def _sanitize(string):
65    # Turn any escaped bytes into unicode 'unknown' char.  If the escaped
66    # bytes happen to be utf-8 they will instead get decoded, even if they
67    # were invalid in the charset the source was supposed to be in.  This
68    # seems like it is not a bad thing; a defect was still registered.
69    original_bytes = string.encode('utf-8', 'surrogateescape')
70    return original_bytes.decode('utf-8', 'replace')
71
72
73
74# Helpers
75
76def formataddr(pair, charset='utf-8'):
77    """The inverse of parseaddr(), this takes a 2-tuple of the form
78    (realname, email_address) and returns the string value suitable
79    for an RFC 2822 From, To or Cc header.
80
81    If the first element of pair is false, then the second element is
82    returned unmodified.
83
84    The optional charset is the character set that is used to encode
85    realname in case realname is not ASCII safe.  Can be an instance of str or
86    a Charset-like object which has a header_encode method.  Default is
87    'utf-8'.
88    """
89    name, address = pair
90    # The address MUST (per RFC) be ascii, so raise a UnicodeError if it isn't.
91    address.encode('ascii')
92    if name:
93        try:
94            name.encode('ascii')
95        except UnicodeEncodeError:
96            if isinstance(charset, str):
97                charset = Charset(charset)
98            encoded_name = charset.header_encode(name)
99            return "%s <%s>" % (encoded_name, address)
100        else:
101            quotes = ''
102            if specialsre.search(name):
103                quotes = '"'
104            name = escapesre.sub(r'\\\g<0>', name)
105            return '%s%s%s <%s>' % (quotes, name, quotes, address)
106    return address
107
108
109
110def getaddresses(fieldvalues):
111    """Return a list of (REALNAME, EMAIL) for each fieldvalue."""
112    all = COMMASPACE.join(fieldvalues)
113    a = _AddressList(all)
114    return a.addresslist
115
116
117def _format_timetuple_and_zone(timetuple, zone):
118    return '%s, %02d %s %04d %02d:%02d:%02d %s' % (
119        ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'][timetuple[6]],
120        timetuple[2],
121        ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
122         'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][timetuple[1] - 1],
123        timetuple[0], timetuple[3], timetuple[4], timetuple[5],
124        zone)
125
126def formatdate(timeval=None, localtime=False, usegmt=False):
127    """Returns a date string as specified by RFC 2822, e.g.:
128
129    Fri, 09 Nov 2001 01:08:47 -0000
130
131    Optional timeval if given is a floating point time value as accepted by
132    gmtime() and localtime(), otherwise the current time is used.
133
134    Optional localtime is a flag that when True, interprets timeval, and
135    returns a date relative to the local timezone instead of UTC, properly
136    taking daylight savings time into account.
137
138    Optional argument usegmt means that the timezone is written out as
139    an ascii string, not numeric one (so "GMT" instead of "+0000"). This
140    is needed for HTTP, and is only used when localtime==False.
141    """
142    # Note: we cannot use strftime() because that honors the locale and RFC
143    # 2822 requires that day and month names be the English abbreviations.
144    if timeval is None:
145        timeval = time.time()
146    if localtime or usegmt:
147        dt = datetime.datetime.fromtimestamp(timeval, datetime.timezone.utc)
148    else:
149        dt = datetime.datetime.utcfromtimestamp(timeval)
150    if localtime:
151        dt = dt.astimezone()
152        usegmt = False
153    return format_datetime(dt, usegmt)
154
155def format_datetime(dt, usegmt=False):
156    """Turn a datetime into a date string as specified in RFC 2822.
157
158    If usegmt is True, dt must be an aware datetime with an offset of zero.  In
159    this case 'GMT' will be rendered instead of the normal +0000 required by
160    RFC2822.  This is to support HTTP headers involving date stamps.
161    """
162    now = dt.timetuple()
163    if usegmt:
164        if dt.tzinfo is None or dt.tzinfo != datetime.timezone.utc:
165            raise ValueError("usegmt option requires a UTC datetime")
166        zone = 'GMT'
167    elif dt.tzinfo is None:
168        zone = '-0000'
169    else:
170        zone = dt.strftime("%z")
171    return _format_timetuple_and_zone(now, zone)
172
173
174def make_msgid(idstring=None, domain=None):
175    """Returns a string suitable for RFC 2822 compliant Message-ID, e.g:
176
177    <142480216486.20800.16526388040877946887@nightshade.la.mastaler.com>
178
179    Optional idstring if given is a string used to strengthen the
180    uniqueness of the message id.  Optional domain if given provides the
181    portion of the message id after the '@'.  It defaults to the locally
182    defined hostname.
183    """
184    timeval = int(time.time()*100)
185    pid = os.getpid()
186    randint = random.getrandbits(64)
187    if idstring is None:
188        idstring = ''
189    else:
190        idstring = '.' + idstring
191    if domain is None:
192        domain = socket.getfqdn()
193    msgid = '<%d.%d.%d%s@%s>' % (timeval, pid, randint, idstring, domain)
194    return msgid
195
196
197def parsedate_to_datetime(data):
198    *dtuple, tz = _parsedate_tz(data)
199    if tz is None:
200        return datetime.datetime(*dtuple[:6])
201    return datetime.datetime(*dtuple[:6],
202            tzinfo=datetime.timezone(datetime.timedelta(seconds=tz)))
203
204
205def parseaddr(addr):
206    """
207    Parse addr into its constituent realname and email address parts.
208
209    Return a tuple of realname and email address, unless the parse fails, in
210    which case return a 2-tuple of ('', '').
211    """
212    addrs = _AddressList(addr).addresslist
213    if not addrs:
214        return '', ''
215    return addrs[0]
216
217
218# rfc822.unquote() doesn't properly de-backslash-ify in Python pre-2.3.
219def unquote(str):
220    """Remove quotes from a string."""
221    if len(str) > 1:
222        if str.startswith('"') and str.endswith('"'):
223            return str[1:-1].replace('\\\\', '\\').replace('\\"', '"')
224        if str.startswith('<') and str.endswith('>'):
225            return str[1:-1]
226    return str
227
228
229
230# RFC2231-related functions - parameter encoding and decoding
231def decode_rfc2231(s):
232    """Decode string according to RFC 2231"""
233    parts = s.split(TICK, 2)
234    if len(parts) <= 2:
235        return None, None, s
236    return parts
237
238
239def encode_rfc2231(s, charset=None, language=None):
240    """Encode string according to RFC 2231.
241
242    If neither charset nor language is given, then s is returned as-is.  If
243    charset is given but not language, the string is encoded using the empty
244    string for language.
245    """
246    s = urllib.parse.quote(s, safe='', encoding=charset or 'ascii')
247    if charset is None and language is None:
248        return s
249    if language is None:
250        language = ''
251    return "%s'%s'%s" % (charset, language, s)
252
253
254rfc2231_continuation = re.compile(r'^(?P<name>\w+)\*((?P<num>[0-9]+)\*?)?$',
255    re.ASCII)
256
257def decode_params(params):
258    """Decode parameters list according to RFC 2231.
259
260    params is a sequence of 2-tuples containing (param name, string value).
261    """
262    new_params = [params[0]]
263    # Map parameter's name to a list of continuations.  The values are a
264    # 3-tuple of the continuation number, the string value, and a flag
265    # specifying whether a particular segment is %-encoded.
266    rfc2231_params = {}
267    for name, value in params[1:]:
268        encoded = name.endswith('*')
269        value = unquote(value)
270        mo = rfc2231_continuation.match(name)
271        if mo:
272            name, num = mo.group('name', 'num')
273            if num is not None:
274                num = int(num)
275            rfc2231_params.setdefault(name, []).append((num, value, encoded))
276        else:
277            new_params.append((name, '"%s"' % quote(value)))
278    if rfc2231_params:
279        for name, continuations in rfc2231_params.items():
280            value = []
281            extended = False
282            # Sort by number
283            continuations.sort()
284            # And now append all values in numerical order, converting
285            # %-encodings for the encoded segments.  If any of the
286            # continuation names ends in a *, then the entire string, after
287            # decoding segments and concatenating, must have the charset and
288            # language specifiers at the beginning of the string.
289            for num, s, encoded in continuations:
290                if encoded:
291                    # Decode as "latin-1", so the characters in s directly
292                    # represent the percent-encoded octet values.
293                    # collapse_rfc2231_value treats this as an octet sequence.
294                    s = urllib.parse.unquote(s, encoding="latin-1")
295                    extended = True
296                value.append(s)
297            value = quote(EMPTYSTRING.join(value))
298            if extended:
299                charset, language, value = decode_rfc2231(value)
300                new_params.append((name, (charset, language, '"%s"' % value)))
301            else:
302                new_params.append((name, '"%s"' % value))
303    return new_params
304
305def collapse_rfc2231_value(value, errors='replace',
306                           fallback_charset='us-ascii'):
307    if not isinstance(value, tuple) or len(value) != 3:
308        return unquote(value)
309    # While value comes to us as a unicode string, we need it to be a bytes
310    # object.  We do not want bytes() normal utf-8 decoder, we want a straight
311    # interpretation of the string as character bytes.
312    charset, language, text = value
313    if charset is None:
314        # Issue 17369: if charset/lang is None, decode_rfc2231 couldn't parse
315        # the value, so use the fallback_charset.
316        charset = fallback_charset
317    rawbytes = bytes(text, 'raw-unicode-escape')
318    try:
319        return str(rawbytes, charset, errors)
320    except LookupError:
321        # charset is not a known codec.
322        return unquote(text)
323
324
325#
326# datetime doesn't provide a localtime function yet, so provide one.  Code
327# adapted from the patch in issue 9527.  This may not be perfect, but it is
328# better than not having it.
329#
330
331def localtime(dt=None, isdst=-1):
332    """Return local time as an aware datetime object.
333
334    If called without arguments, return current time.  Otherwise *dt*
335    argument should be a datetime instance, and it is converted to the
336    local time zone according to the system time zone database.  If *dt* is
337    naive (that is, dt.tzinfo is None), it is assumed to be in local time.
338    In this case, a positive or zero value for *isdst* causes localtime to
339    presume initially that summer time (for example, Daylight Saving Time)
340    is or is not (respectively) in effect for the specified time.  A
341    negative value for *isdst* causes the localtime() function to attempt
342    to divine whether summer time is in effect for the specified time.
343
344    """
345    if dt is None:
346        return datetime.datetime.now(datetime.timezone.utc).astimezone()
347    if dt.tzinfo is not None:
348        return dt.astimezone()
349    # We have a naive datetime.  Convert to a (localtime) timetuple and pass to
350    # system mktime together with the isdst hint.  System mktime will return
351    # seconds since epoch.
352    tm = dt.timetuple()[:-1] + (isdst,)
353    seconds = time.mktime(tm)
354    localtm = time.localtime(seconds)
355    try:
356        delta = datetime.timedelta(seconds=localtm.tm_gmtoff)
357        tz = datetime.timezone(delta, localtm.tm_zone)
358    except AttributeError:
359        # Compute UTC offset and compare with the value implied by tm_isdst.
360        # If the values match, use the zone name implied by tm_isdst.
361        delta = dt - datetime.datetime(*time.gmtime(seconds)[:6])
362        dst = time.daylight and localtm.tm_isdst > 0
363        gmtoff = -(time.altzone if dst else time.timezone)
364        if delta == datetime.timedelta(seconds=gmtoff):
365            tz = datetime.timezone(delta, time.tzname[dst])
366        else:
367            tz = datetime.timezone(delta)
368    return dt.replace(tzinfo=tz)
369