# Copyright (C) 2001-2010 Python Software Foundation

[0] Fix | Delete

# Author: Barry Warsaw

[1] Fix | Delete

# Contact: email-sig@python.org

[2] Fix | Delete

[3] Fix | Delete

"""Miscellaneous utilities."""

[4] Fix | Delete

[5] Fix | Delete

__all__ = [

[6] Fix | Delete

'collapse_rfc2231_value',

[7] Fix | Delete

'decode_params',

[8] Fix | Delete

'decode_rfc2231',

[9] Fix | Delete

'encode_rfc2231',

[10] Fix | Delete

'formataddr',

[11] Fix | Delete

'formatdate',

[12] Fix | Delete

'getaddresses',

[13] Fix | Delete

'make_msgid',

[14] Fix | Delete

'mktime_tz',

[15] Fix | Delete

'parseaddr',

[16] Fix | Delete

'parsedate',

[17] Fix | Delete

'parsedate_tz',

[18] Fix | Delete

'unquote',

[19] Fix | Delete

]

[20] Fix | Delete

[21] Fix | Delete

import os

[22] Fix | Delete

import re

[23] Fix | Delete

import time

[24] Fix | Delete

import base64

[25] Fix | Delete

import random

[26] Fix | Delete

import socket

[27] Fix | Delete

import urllib

[28] Fix | Delete

import warnings

[29] Fix | Delete

[30] Fix | Delete

from email._parseaddr import quote

[31] Fix | Delete

from email._parseaddr import AddressList as _AddressList

[32] Fix | Delete

from email._parseaddr import mktime_tz

[33] Fix | Delete

[34] Fix | Delete

# We need wormarounds for bugs in these methods in older Pythons (see below)

[35] Fix | Delete

from email._parseaddr import parsedate as _parsedate

[36] Fix | Delete

from email._parseaddr import parsedate_tz as _parsedate_tz

[37] Fix | Delete

[38] Fix | Delete

from quopri import decodestring as _qdecode

[39] Fix | Delete

[40] Fix | Delete

# Intrapackage imports

[41] Fix | Delete

from email.encoders import _bencode, _qencode

[42] Fix | Delete

[43] Fix | Delete

COMMASPACE = ', '

[44] Fix | Delete

EMPTYSTRING = ''

[45] Fix | Delete

UEMPTYSTRING = u''

[46] Fix | Delete

CRLF = '\r\n'

[47] Fix | Delete

TICK = "'"

[48] Fix | Delete

[49] Fix | Delete

specialsre = re.compile(r'[][\\()<>@,:;".]')

[50] Fix | Delete

escapesre = re.compile(r'[][\\()"]')

[51] Fix | Delete

[52] Fix | Delete

[53] Fix | Delete



[54] Fix | Delete

# Helpers

[55] Fix | Delete

[56] Fix | Delete

def _identity(s):

[57] Fix | Delete

return s

[58] Fix | Delete

[59] Fix | Delete

[60] Fix | Delete

def _bdecode(s):

[61] Fix | Delete

"""Decodes a base64 string.

[62] Fix | Delete

[63] Fix | Delete

This function is equivalent to base64.decodestring and it's retained only

[64] Fix | Delete

for backward compatibility. It used to remove the last \\n of the decoded

[65] Fix | Delete

string, if it had any (see issue 7143).

[66] Fix | Delete

"""

[67] Fix | Delete

if not s:

[68] Fix | Delete

return s

[69] Fix | Delete

return base64.decodestring(s)

[70] Fix | Delete

[71] Fix | Delete

[72] Fix | Delete



[73] Fix | Delete

def fix_eols(s):

[74] Fix | Delete

"""Replace all line-ending characters with \\r\\n."""

[75] Fix | Delete

# Fix newlines with no preceding carriage return

[76] Fix | Delete

s = re.sub(r'(?<!\r)\n', CRLF, s)

[77] Fix | Delete

# Fix carriage returns with no following newline

[78] Fix | Delete

s = re.sub(r'\r(?!\n)', CRLF, s)

[79] Fix | Delete

return s

[80] Fix | Delete

[81] Fix | Delete

[82] Fix | Delete



[83] Fix | Delete

def formataddr(pair):

[84] Fix | Delete

"""The inverse of parseaddr(), this takes a 2-tuple of the form

[85] Fix | Delete

(realname, email_address) and returns the string value suitable

[86] Fix | Delete

for an RFC 2822 From, To or Cc header.

[87] Fix | Delete

[88] Fix | Delete

If the first element of pair is false, then the second element is

[89] Fix | Delete

returned unmodified.

[90] Fix | Delete

"""

[91] Fix | Delete

name, address = pair

[92] Fix | Delete

if name:

[93] Fix | Delete

quotes = ''

[94] Fix | Delete

if specialsre.search(name):

[95] Fix | Delete

quotes = '"'

[96] Fix | Delete

name = escapesre.sub(r'\\\g<0>', name)

[97] Fix | Delete

return '%s%s%s <%s>' % (quotes, name, quotes, address)

[98] Fix | Delete

return address

[99] Fix | Delete

[100] Fix | Delete

[101] Fix | Delete



[102] Fix | Delete

def getaddresses(fieldvalues):

[103] Fix | Delete

"""Return a list of (REALNAME, EMAIL) for each fieldvalue."""

[104] Fix | Delete

all = COMMASPACE.join(fieldvalues)

[105] Fix | Delete

a = _AddressList(all)

[106] Fix | Delete

return a.addresslist

[107] Fix | Delete

[108] Fix | Delete

[109] Fix | Delete



[110] Fix | Delete

ecre = re.compile(r'''

[111] Fix | Delete

=\? # literal =?

[112] Fix | Delete

(?P<charset>[^?]*?) # non-greedy up to the next ? is the charset

[113] Fix | Delete

\? # literal ?

[114] Fix | Delete

(?P<encoding>[qb]) # either a "q" or a "b", case insensitive

[115] Fix | Delete

\? # literal ?

[116] Fix | Delete

(?P<atom>.*?) # non-greedy up to the next ?= is the atom

[117] Fix | Delete

\?= # literal ?=

[118] Fix | Delete

''', re.VERBOSE | re.IGNORECASE)

[119] Fix | Delete

[120] Fix | Delete

[121] Fix | Delete



[122] Fix | Delete

def formatdate(timeval=None, localtime=False, usegmt=False):

[123] Fix | Delete

"""Returns a date string as specified by RFC 2822, e.g.:

[124] Fix | Delete

[125] Fix | Delete

Fri, 09 Nov 2001 01:08:47 -0000

[126] Fix | Delete

[127] Fix | Delete

Optional timeval if given is a floating point time value as accepted by

[128] Fix | Delete

gmtime() and localtime(), otherwise the current time is used.

[129] Fix | Delete

[130] Fix | Delete

Optional localtime is a flag that when True, interprets timeval, and

[131] Fix | Delete

returns a date relative to the local timezone instead of UTC, properly

[132] Fix | Delete

taking daylight savings time into account.

[133] Fix | Delete

[134] Fix | Delete

Optional argument usegmt means that the timezone is written out as

[135] Fix | Delete

an ascii string, not numeric one (so "GMT" instead of "+0000"). This

[136] Fix | Delete

is needed for HTTP, and is only used when localtime==False.

[137] Fix | Delete

"""

[138] Fix | Delete

# Note: we cannot use strftime() because that honors the locale and RFC

[139] Fix | Delete

# 2822 requires that day and month names be the English abbreviations.

[140] Fix | Delete

if timeval is None:

[141] Fix | Delete

timeval = time.time()

[142] Fix | Delete

if localtime:

[143] Fix | Delete

now = time.localtime(timeval)

[144] Fix | Delete

# Calculate timezone offset, based on whether the local zone has

[145] Fix | Delete

# daylight savings time, and whether DST is in effect.

[146] Fix | Delete

if time.daylight and now[-1]:

[147] Fix | Delete

offset = time.altzone

[148] Fix | Delete

else:

[149] Fix | Delete

offset = time.timezone

[150] Fix | Delete

hours, minutes = divmod(abs(offset), 3600)

[151] Fix | Delete

# Remember offset is in seconds west of UTC, but the timezone is in

[152] Fix | Delete

# minutes east of UTC, so the signs differ.

[153] Fix | Delete

if offset > 0:

[154] Fix | Delete

sign = '-'

[155] Fix | Delete

else:

[156] Fix | Delete

sign = '+'

[157] Fix | Delete

zone = '%s%02d%02d' % (sign, hours, minutes // 60)

[158] Fix | Delete

else:

[159] Fix | Delete

now = time.gmtime(timeval)

[160] Fix | Delete

# Timezone offset is always -0000

[161] Fix | Delete

if usegmt:

[162] Fix | Delete

zone = 'GMT'

[163] Fix | Delete

else:

[164] Fix | Delete

zone = '-0000'

[165] Fix | Delete

return '%s, %02d %s %04d %02d:%02d:%02d %s' % (

[166] Fix | Delete

['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'][now[6]],

[167] Fix | Delete

now[2],

[168] Fix | Delete

['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',

[169] Fix | Delete

'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][now[1] - 1],

[170] Fix | Delete

now[0], now[3], now[4], now[5],

[171] Fix | Delete

zone)

[172] Fix | Delete

[173] Fix | Delete

[174] Fix | Delete



[175] Fix | Delete

def make_msgid(idstring=None):

[176] Fix | Delete

"""Returns a string suitable for RFC 2822 compliant Message-ID, e.g:

[177] Fix | Delete

[178] Fix | Delete

<142480216486.20800.16526388040877946887@nightshade.la.mastaler.com>

[179] Fix | Delete

[180] Fix | Delete

Optional idstring if given is a string used to strengthen the

[181] Fix | Delete

uniqueness of the message id.

[182] Fix | Delete

"""

[183] Fix | Delete

timeval = int(time.time()*100)

[184] Fix | Delete

pid = os.getpid()

[185] Fix | Delete

randint = random.getrandbits(64)

[186] Fix | Delete

if idstring is None:

[187] Fix | Delete

idstring = ''

[188] Fix | Delete

else:

[189] Fix | Delete

idstring = '.' + idstring

[190] Fix | Delete

idhost = socket.getfqdn()

[191] Fix | Delete

msgid = '<%d.%d.%d%s@%s>' % (timeval, pid, randint, idstring, idhost)

[192] Fix | Delete

return msgid

[193] Fix | Delete

[194] Fix | Delete

[195] Fix | Delete



[196] Fix | Delete

# These functions are in the standalone mimelib version only because they've

[197] Fix | Delete

# subsequently been fixed in the latest Python versions. We use this to worm

[198] Fix | Delete

# around broken older Pythons.

[199] Fix | Delete

def parsedate(data):

[200] Fix | Delete

if not data:

[201] Fix | Delete

return None

[202] Fix | Delete

return _parsedate(data)

[203] Fix | Delete

[204] Fix | Delete

[205] Fix | Delete

def parsedate_tz(data):

[206] Fix | Delete

if not data:

[207] Fix | Delete

return None

[208] Fix | Delete

return _parsedate_tz(data)

[209] Fix | Delete

[210] Fix | Delete

[211] Fix | Delete

def parseaddr(addr):

[212] Fix | Delete

"""

[213] Fix | Delete

Parse addr into its constituent realname and email address parts.

[214] Fix | Delete

[215] Fix | Delete

Return a tuple of realname and email address, unless the parse fails, in

[216] Fix | Delete

which case return a 2-tuple of ('', '').

[217] Fix | Delete

"""

[218] Fix | Delete

addrs = _AddressList(addr).addresslist

[219] Fix | Delete

if not addrs:

[220] Fix | Delete

return '', ''

[221] Fix | Delete

return addrs[0]

[222] Fix | Delete

[223] Fix | Delete

[224] Fix | Delete

# rfc822.unquote() doesn't properly de-backslash-ify in Python pre-2.3.

[225] Fix | Delete

def unquote(str):

[226] Fix | Delete

"""Remove quotes from a string."""

[227] Fix | Delete

if len(str) > 1:

[228] Fix | Delete

if str.startswith('"') and str.endswith('"'):

[229] Fix | Delete

return str[1:-1].replace('\\\\', '\\').replace('\\"', '"')

[230] Fix | Delete

if str.startswith('<') and str.endswith('>'):

[231] Fix | Delete

return str[1:-1]

[232] Fix | Delete

return str

[233] Fix | Delete

[234] Fix | Delete

[235] Fix | Delete



[236] Fix | Delete

# RFC2231-related functions - parameter encoding and decoding

[237] Fix | Delete

def decode_rfc2231(s):

[238] Fix | Delete

"""Decode string according to RFC 2231"""

[239] Fix | Delete

parts = s.split(TICK, 2)

[240] Fix | Delete

if len(parts) <= 2:

[241] Fix | Delete

return None, None, s

[242] Fix | Delete

return parts

[243] Fix | Delete

[244] Fix | Delete

[245] Fix | Delete

def encode_rfc2231(s, charset=None, language=None):

[246] Fix | Delete

"""Encode string according to RFC 2231.

[247] Fix | Delete

[248] Fix | Delete

If neither charset nor language is given, then s is returned as-is. If

[249] Fix | Delete

charset is given but not language, the string is encoded using the empty

[250] Fix | Delete

string for language.

[251] Fix | Delete

"""

[252] Fix | Delete

import urllib

[253] Fix | Delete

s = urllib.quote(s, safe='')

[254] Fix | Delete

if charset is None and language is None:

[255] Fix | Delete

return s

[256] Fix | Delete

if language is None:

[257] Fix | Delete

language = ''

[258] Fix | Delete

return "%s'%s'%s" % (charset, language, s)

[259] Fix | Delete

[260] Fix | Delete

[261] Fix | Delete

rfc2231_continuation = re.compile(r'^(?P<name>\w+)\*((?P<num>[0-9]+)\*?)?$')

[262] Fix | Delete

[263] Fix | Delete

def decode_params(params):

[264] Fix | Delete

"""Decode parameters list according to RFC 2231.

[265] Fix | Delete

[266] Fix | Delete

params is a sequence of 2-tuples containing (param name, string value).

[267] Fix | Delete

"""

[268] Fix | Delete

# Copy params so we don't mess with the original

[269] Fix | Delete

params = params[:]

[270] Fix | Delete

new_params = []

[271] Fix | Delete

# Map parameter's name to a list of continuations. The values are a

[272] Fix | Delete

# 3-tuple of the continuation number, the string value, and a flag

[273] Fix | Delete

# specifying whether a particular segment is %-encoded.

[274] Fix | Delete

rfc2231_params = {}

[275] Fix | Delete

name, value = params.pop(0)

[276] Fix | Delete

new_params.append((name, value))

[277] Fix | Delete

while params:

[278] Fix | Delete

name, value = params.pop(0)

[279] Fix | Delete

if name.endswith('*'):

[280] Fix | Delete

encoded = True

[281] Fix | Delete

else:

[282] Fix | Delete

encoded = False

[283] Fix | Delete

value = unquote(value)

[284] Fix | Delete

mo = rfc2231_continuation.match(name)

[285] Fix | Delete

if mo:

[286] Fix | Delete

name, num = mo.group('name', 'num')

[287] Fix | Delete

if num is not None:

[288] Fix | Delete

num = int(num)

[289] Fix | Delete

rfc2231_params.setdefault(name, []).append((num, value, encoded))

[290] Fix | Delete

else:

[291] Fix | Delete

new_params.append((name, '"%s"' % quote(value)))

[292] Fix | Delete

if rfc2231_params:

[293] Fix | Delete

for name, continuations in rfc2231_params.items():

[294] Fix | Delete

value = []

[295] Fix | Delete

extended = False

[296] Fix | Delete

# Sort by number

[297] Fix | Delete

continuations.sort()

[298] Fix | Delete

# And now append all values in numerical order, converting

[299] Fix | Delete

# %-encodings for the encoded segments. If any of the

[300] Fix | Delete

# continuation names ends in a *, then the entire string, after

[301] Fix | Delete

# decoding segments and concatenating, must have the charset and

[302] Fix | Delete

# language specifiers at the beginning of the string.

[303] Fix | Delete

for num, s, encoded in continuations:

[304] Fix | Delete

if encoded:

[305] Fix | Delete

s = urllib.unquote(s)

[306] Fix | Delete

extended = True

[307] Fix | Delete

value.append(s)

[308] Fix | Delete

value = quote(EMPTYSTRING.join(value))

[309] Fix | Delete

if extended:

[310] Fix | Delete

charset, language, value = decode_rfc2231(value)

[311] Fix | Delete

new_params.append((name, (charset, language, '"%s"' % value)))

[312] Fix | Delete

else:

[313] Fix | Delete

new_params.append((name, '"%s"' % value))

[314] Fix | Delete

return new_params

[315] Fix | Delete

[316] Fix | Delete

def collapse_rfc2231_value(value, errors='replace',

[317] Fix | Delete

fallback_charset='us-ascii'):

[318] Fix | Delete

if isinstance(value, tuple):

[319] Fix | Delete

rawval = unquote(value[2])

[320] Fix | Delete

charset = value[0] or 'us-ascii'

[321] Fix | Delete

try:

[322] Fix | Delete

return unicode(rawval, charset, errors)

[323] Fix | Delete

except LookupError:

[324] Fix | Delete

# XXX charset is unknown to Python.

[325] Fix | Delete

return unicode(rawval, fallback_charset, errors)

[326] Fix | Delete

else:

[327] Fix | Delete

return unquote(value)

[328] Fix | Delete

[329] Fix | Delete