Lib/email/quopriMIME.py

   1 # Copyright (C) 2001-2004 Python Software Foundation
   2 # Author: che@debian.org (Ben Gertzfield)
   3
   4 """Quoted-printable content transfer encoding per RFCs 2045-2047.
   5
   6 This module handles the content transfer encoding method defined in RFC 2045
   7 to encode US ASCII-like 8-bit data called `quoted-printable'.  It is used to
   8 safely encode text that is in a character set similar to the 7-bit US ASCII
   9 character set, but that includes some 8-bit characters that are normally not
  10 allowed in email bodies or headers.
  11
  12 Quoted-printable is very space-inefficient for encoding binary files; use the
  13 email.base64MIME module for that instead.
  14
  15 This module provides an interface to encode and decode both headers and bodies
  16 with quoted-printable encoding.
  17
  18 RFC 2045 defines a method for including character set information in an
  19 `encoded-word' in a header.  This method is commonly used for 8-bit real names
  20 in To:/From:/Cc: etc. fields, as well as Subject: lines.
  21
  22 This module does not do the line wrapping or end-of-line character
  23 conversion necessary for proper internationalized headers; it only
  24 does dumb encoding and decoding.  To deal with the various line
  25 wrapping issues, use the email.Header module.
  26 """
  27
  28 import re
  29 from string import hexdigits
  30 from email.Utils import fix_eols
  31
  32 CRLF = '\r\n'
  33 NL = '\n'
  34
  35 # See also Charset.py
  36 MISC_LEN = 7
  37
  38 hqre = re.compile(r'[^-a-zA-Z0-9!*+/ ]')
  39 bqre = re.compile(r'[^ !-<>-~\t]')
  40
  41
  42 \f
  43 # Helpers
  44 def header_quopri_check(c):
  45     """Return True if the character should be escaped with header quopri."""
  46     return hqre.match(c) and True
  47
  48
  49 def body_quopri_check(c):
  50     """Return True if the character should be escaped with body quopri."""
  51     return bqre.match(c) and True
  52
  53
  54 def header_quopri_len(s):
  55     """Return the length of str when it is encoded with header quopri."""
  56     count = 0
  57     for c in s:
  58         if hqre.match(c):
  59             count += 3
  60         else:
  61             count += 1
  62     return count
  63
  64
  65 def body_quopri_len(str):
  66     """Return the length of str when it is encoded with body quopri."""
  67     count = 0
  68     for c in str:
  69         if bqre.match(c):
  70             count += 3
  71         else:
  72             count += 1
  73     return count
  74
  75
  76 def _max_append(L, s, maxlen, extra=''):
  77     if not L:
  78         L.append(s.lstrip())
  79     elif len(L[-1]) + len(s) <= maxlen:
  80         L[-1] += extra + s
  81     else:
  82         L.append(s.lstrip())
  83
  84
  85 def unquote(s):
  86     """Turn a string in the form =AB to the ASCII character with value 0xab"""
  87     return chr(int(s[1:3], 16))
  88
  89
  90 def quote(c):
  91     return "=%02X" % ord(c)
  92
  93
  94 \f
  95 def header_encode(header, charset="iso-8859-1", keep_eols=False,
  96                   maxlinelen=76, eol=NL):
  97     """Encode a single header line with quoted-printable (like) encoding.
  98
  99     Defined in RFC 2045, this `Q' encoding is similar to quoted-printable, but
 100     used specifically for email header fields to allow charsets with mostly 7
 101     bit characters (and some 8 bit) to remain more or less readable in non-RFC
 102     2045 aware mail clients.
 103
 104     charset names the character set to use to encode the header.  It defaults
 105     to iso-8859-1.
 106
 107     The resulting string will be in the form:
 108
 109     "=?charset?q?I_f=E2rt_in_your_g=E8n=E8ral_dire=E7tion?\\n
 110       =?charset?q?Silly_=C8nglish_Kn=EEghts?="
 111
 112     with each line wrapped safely at, at most, maxlinelen characters (defaults
 113     to 76 characters).  If maxlinelen is None, the entire string is encoded in
 114     one chunk with no splitting.
 115
 116     End-of-line characters (\\r, \\n, \\r\\n) will be automatically converted
 117     to the canonical email line separator \\r\\n unless the keep_eols
 118     parameter is True (the default is False).
 119
 120     Each line of the header will be terminated in the value of eol, which
 121     defaults to "\\n".  Set this to "\\r\\n" if you are using the result of
 122     this function directly in email.
 123     """
 124     # Return empty headers unchanged
 125     if not header:
 126         return header
 127
 128     if not keep_eols:
 129         header = fix_eols(header)
 130
 131     # Quopri encode each line, in encoded chunks no greater than maxlinelen in
 132     # length, after the RFC chrome is added in.
 133     quoted = []
 134     if maxlinelen is None:
 135         # An obnoxiously large number that's good enough
 136         max_encoded = 100000
 137     else:
 138         max_encoded = maxlinelen - len(charset) - MISC_LEN - 1
 139
 140     for c in header:
 141         # Space may be represented as _ instead of =20 for readability
 142         if c == ' ':
 143             _max_append(quoted, '_', max_encoded)
 144         # These characters can be included verbatim
 145         elif not hqre.match(c):
 146             _max_append(quoted, c, max_encoded)
 147         # Otherwise, replace with hex value like =E2
 148         else:
 149             _max_append(quoted, "=%02X" % ord(c), max_encoded)
 150
 151     # Now add the RFC chrome to each encoded chunk and glue the chunks
 152     # together.  BAW: should we be able to specify the leading whitespace in
 153     # the joiner?
 154     joiner = eol + ' '
 155     return joiner.join(['=?%s?q?%s?=' % (charset, line) for line in quoted])
 156
 157
 158 \f
 159 def encode(body, binary=False, maxlinelen=76, eol=NL):
 160     """Encode with quoted-printable, wrapping at maxlinelen characters.
 161
 162     If binary is False (the default), end-of-line characters will be converted
 163     to the canonical email end-of-line sequence \\r\\n.  Otherwise they will
 164     be left verbatim.
 165
 166     Each line of encoded text will end with eol, which defaults to "\\n".  Set
 167     this to "\\r\\n" if you will be using the result of this function directly
 168     in an email.
 169
 170     Each line will be wrapped at, at most, maxlinelen characters (defaults to
 171     76 characters).  Long lines will have the `soft linefeed' quoted-printable
 172     character "=" appended to them, so the decoded text will be identical to
 173     the original text.
 174     """
 175     if not body:
 176         return body
 177
 178     if not binary:
 179         body = fix_eols(body)
 180
 181     # BAW: We're accumulating the body text by string concatenation.  That
 182     # can't be very efficient, but I don't have time now to rewrite it.  It
 183     # just feels like this algorithm could be more efficient.
 184     encoded_body = ''
 185     lineno = -1
 186     # Preserve line endings here so we can check later to see an eol needs to
 187     # be added to the output later.
 188     lines = body.splitlines(1)
 189     for line in lines:
 190         # But strip off line-endings for processing this line.
 191         if line.endswith(CRLF):
 192             line = line[:-2]
 193         elif line[-1] in CRLF:
 194             line = line[:-1]
 195
 196         lineno += 1
 197         encoded_line = ''
 198         prev = None
 199         linelen = len(line)
 200         # Now we need to examine every character to see if it needs to be
 201         # quopri encoded.  BAW: again, string concatenation is inefficient.
 202         for j in range(linelen):
 203             c = line[j]
 204             prev = c
 205             if bqre.match(c):
 206                 c = quote(c)
 207             elif j+1 == linelen:
 208                 # Check for whitespace at end of line; special case
 209                 if c not in ' \t':
 210                     encoded_line += c
 211                 prev = c
 212                 continue
 213             # Check to see to see if the line has reached its maximum length
 214             if len(encoded_line) + len(c) >= maxlinelen:
 215                 encoded_body += encoded_line + '=' + eol
 216                 encoded_line = ''
 217             encoded_line += c
 218         # Now at end of line..
 219         if prev and prev in ' \t':
 220             # Special case for whitespace at end of file
 221             if lineno + 1 == len(lines):
 222                 prev = quote(prev)
 223                 if len(encoded_line) + len(prev) > maxlinelen:
 224                     encoded_body += encoded_line + '=' + eol + prev
 225                 else:
 226                     encoded_body += encoded_line + prev
 227             # Just normal whitespace at end of line
 228             else:
 229                 encoded_body += encoded_line + prev + '=' + eol
 230             encoded_line = ''
 231         # Now look at the line we just finished and it has a line ending, we
 232         # need to add eol to the end of the line.
 233         if lines[lineno].endswith(CRLF) or lines[lineno][-1] in CRLF:
 234             encoded_body += encoded_line + eol
 235         else:
 236             encoded_body += encoded_line
 237         encoded_line = ''
 238     return encoded_body
 239
 240
 241 # For convenience and backwards compatibility w/ standard base64 module
 242 body_encode = encode
 243 encodestring = encode
 244
 245
 246 \f
 247 # BAW: I'm not sure if the intent was for the signature of this function to be
 248 # the same as base64MIME.decode() or not...
 249 def decode(encoded, eol=NL):
 250     """Decode a quoted-printable string.
 251
 252     Lines are separated with eol, which defaults to \\n.
 253     """
 254     if not encoded:
 255         return encoded
 256     # BAW: see comment in encode() above.  Again, we're building up the
 257     # decoded string with string concatenation, which could be done much more
 258     # efficiently.
 259     decoded = ''
 260
 261     for line in encoded.splitlines():
 262         line = line.rstrip()
 263         if not line:
 264             decoded += eol
 265             continue
 266
 267         i = 0
 268         n = len(line)
 269         while i < n:
 270             c = line[i]
 271             if c <> '=':
 272                 decoded += c
 273                 i += 1
 274             # Otherwise, c == "=".  Are we at the end of the line?  If so, add
 275             # a soft line break.
 276             elif i+1 == n:
 277                 i += 1
 278                 continue
 279             # Decode if in form =AB
 280             elif i+2 < n and line[i+1] in hexdigits and line[i+2] in hexdigits:
 281                 decoded += unquote(line[i:i+3])
 282                 i += 3
 283             # Otherwise, not in form =AB, pass literally
 284             else:
 285                 decoded += c
 286                 i += 1
 287
 288             if i == n:
 289                 decoded += eol
 290     # Special case if original string did not end with eol
 291     if not encoded.endswith(eol) and decoded.endswith(eol):
 292         decoded = decoded[:-1]
 293     return decoded
 294
 295
 296 # For convenience and backwards compatibility w/ standard base64 module
 297 body_decode = decode
 298 decodestring = decode
 299
 300
 301 \f
 302 def _unquote_match(match):
 303     """Turn a match in the form =AB to the ASCII character with value 0xab"""
 304     s = match.group(0)
 305     return unquote(s)
 306
 307
 308 # Header decoding is done a bit differently
 309 def header_decode(s):
 310     """Decode a string encoded with RFC 2045 MIME header `Q' encoding.
 311
 312     This function does not parse a full MIME header value encoded with
 313     quoted-printable (like =?iso-8895-1?q?Hello_World?=) -- please use
 314     the high level email.Header class for that functionality.
 315     """
 316     s = s.replace('_', ' ')
 317     return re.sub(r'=\w{2}', _unquote_match, s)