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