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_length',
33    'decode',
34    'decodestring',
35    'header_decode',
36    'header_encode',
37    'header_length',
38    'quote',
39    'unquote',
40    ]
41
42import re
43
44from string import ascii_letters, digits, hexdigits
45
46CRLF = '\r\n'
47NL = '\n'
48EMPTYSTRING = ''
49
50# Build a mapping of octets to the expansion of that octet.  Since we're only
51# going to have 256 of these things, this isn't terribly inefficient
52# space-wise.  Remember that headers and bodies have different sets of safe
53# characters.  Initialize both maps with the full expansion, and then override
54# the safe bytes with the more compact form.
55_QUOPRI_MAP = ['=%02X' % c for c in range(256)]
56_QUOPRI_HEADER_MAP = _QUOPRI_MAP[:]
57_QUOPRI_BODY_MAP = _QUOPRI_MAP[:]
58
59# Safe header bytes which need no encoding.
60for c in b'-!*+/' + ascii_letters.encode('ascii') + digits.encode('ascii'):
61    _QUOPRI_HEADER_MAP[c] = chr(c)
62# Headers have one other special encoding; spaces become underscores.
63_QUOPRI_HEADER_MAP[ord(' ')] = '_'
64
65# Safe body bytes which need no encoding.
66for c in (b' !"#$%&\'()*+,-./0123456789:;<>'
67          b'?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`'
68          b'abcdefghijklmnopqrstuvwxyz{|}~\t'):
69    _QUOPRI_BODY_MAP[c] = chr(c)
70
71
72
73# Helpers
74def header_check(octet):
75    """Return True if the octet should be escaped with header quopri."""
76    return chr(octet) != _QUOPRI_HEADER_MAP[octet]
77
78
79def body_check(octet):
80    """Return True if the octet should be escaped with body quopri."""
81    return chr(octet) != _QUOPRI_BODY_MAP[octet]
82
83
84def header_length(bytearray):
85    """Return a header quoted-printable encoding length.
86
87    Note that this does not include any RFC 2047 chrome added by
88    `header_encode()`.
89
90    :param bytearray: An array of bytes (a.k.a. octets).
91    :return: The length in bytes of the byte array when it is encoded with
92        quoted-printable for headers.
93    """
94    return sum(len(_QUOPRI_HEADER_MAP[octet]) for octet in bytearray)
95
96
97def body_length(bytearray):
98    """Return a body quoted-printable encoding length.
99
100    :param bytearray: An array of bytes (a.k.a. octets).
101    :return: The length in bytes of the byte array when it is encoded with
102        quoted-printable for bodies.
103    """
104    return sum(len(_QUOPRI_BODY_MAP[octet]) for octet in bytearray)
105
106
107def _max_append(L, s, maxlen, extra=''):
108    if not isinstance(s, str):
109        s = chr(s)
110    if not L:
111        L.append(s.lstrip())
112    elif len(L[-1]) + len(s) <= maxlen:
113        L[-1] += extra + s
114    else:
115        L.append(s.lstrip())
116
117
118def unquote(s):
119    """Turn a string in the form =AB to the ASCII character with value 0xab"""
120    return chr(int(s[1:3], 16))
121
122
123def quote(c):
124    return _QUOPRI_MAP[ord(c)]
125
126
127def header_encode(header_bytes, charset='iso-8859-1'):
128    """Encode a single header line with quoted-printable (like) encoding.
129
130    Defined in RFC 2045, this `Q' encoding is similar to quoted-printable, but
131    used specifically for email header fields to allow charsets with mostly 7
132    bit characters (and some 8 bit) to remain more or less readable in non-RFC
133    2045 aware mail clients.
134
135    charset names the character set to use in the RFC 2046 header.  It
136    defaults to iso-8859-1.
137    """
138    # Return empty headers as an empty string.
139    if not header_bytes:
140        return ''
141    # Iterate over every byte, encoding if necessary.
142    encoded = header_bytes.decode('latin1').translate(_QUOPRI_HEADER_MAP)
143    # Now add the RFC chrome to each encoded chunk and glue the chunks
144    # together.
145    return '=?%s?q?%s?=' % (charset, encoded)
146
147
148_QUOPRI_BODY_ENCODE_MAP = _QUOPRI_BODY_MAP[:]
149for c in b'\r\n':
150    _QUOPRI_BODY_ENCODE_MAP[c] = chr(c)
151
152def body_encode(body, maxlinelen=76, eol=NL):
153    """Encode with quoted-printable, wrapping at maxlinelen characters.
154
155    Each line of encoded text will end with eol, which defaults to "\\n".  Set
156    this to "\\r\\n" if you will be using the result of this function directly
157    in an email.
158
159    Each line will be wrapped at, at most, maxlinelen characters before the
160    eol string (maxlinelen defaults to 76 characters, the maximum value
161    permitted by RFC 2045).  Long lines will have the 'soft line break'
162    quoted-printable character "=" appended to them, so the decoded text will
163    be identical to the original text.
164
165    The minimum maxlinelen is 4 to have room for a quoted character ("=XX")
166    followed by a soft line break.  Smaller values will generate a
167    ValueError.
168
169    """
170
171    if maxlinelen < 4:
172        raise ValueError("maxlinelen must be at least 4")
173    if not body:
174        return body
175
176    # quote special characters
177    body = body.translate(_QUOPRI_BODY_ENCODE_MAP)
178
179    soft_break = '=' + eol
180    # leave space for the '=' at the end of a line
181    maxlinelen1 = maxlinelen - 1
182
183    encoded_body = []
184    append = encoded_body.append
185
186    for line in body.splitlines():
187        # break up the line into pieces no longer than maxlinelen - 1
188        start = 0
189        laststart = len(line) - 1 - maxlinelen
190        while start <= laststart:
191            stop = start + maxlinelen1
192            # make sure we don't break up an escape sequence
193            if line[stop - 2] == '=':
194                append(line[start:stop - 1])
195                start = stop - 2
196            elif line[stop - 1] == '=':
197                append(line[start:stop])
198                start = stop - 1
199            else:
200                append(line[start:stop] + '=')
201                start = stop
202
203        # handle rest of line, special case if line ends in whitespace
204        if line and line[-1] in ' \t':
205            room = start - laststart
206            if room >= 3:
207                # It's a whitespace character at end-of-line, and we have room
208                # for the three-character quoted encoding.
209                q = quote(line[-1])
210            elif room == 2:
211                # There's room for the whitespace character and a soft break.
212                q = line[-1] + soft_break
213            else:
214                # There's room only for a soft break.  The quoted whitespace
215                # will be the only content on the subsequent line.
216                q = soft_break + quote(line[-1])
217            append(line[start:-1] + q)
218        else:
219            append(line[start:])
220
221    # add back final newline if present
222    if body[-1] in CRLF:
223        append('')
224
225    return eol.join(encoded_body)
226
227
228
229# BAW: I'm not sure if the intent was for the signature of this function to be
230# the same as base64MIME.decode() or not...
231def decode(encoded, eol=NL):
232    """Decode a quoted-printable string.
233
234    Lines are separated with eol, which defaults to \\n.
235    """
236    if not encoded:
237        return encoded
238    # BAW: see comment in encode() above.  Again, we're building up the
239    # decoded string with string concatenation, which could be done much more
240    # efficiently.
241    decoded = ''
242
243    for line in encoded.splitlines():
244        line = line.rstrip()
245        if not line:
246            decoded += eol
247            continue
248
249        i = 0
250        n = len(line)
251        while i < n:
252            c = line[i]
253            if c != '=':
254                decoded += c
255                i += 1
256            # Otherwise, c == "=".  Are we at the end of the line?  If so, add
257            # a soft line break.
258            elif i+1 == n:
259                i += 1
260                continue
261            # Decode if in form =AB
262            elif i+2 < n and line[i+1] in hexdigits and line[i+2] in hexdigits:
263                decoded += unquote(line[i:i+3])
264                i += 3
265            # Otherwise, not in form =AB, pass literally
266            else:
267                decoded += c
268                i += 1
269
270            if i == n:
271                decoded += eol
272    # Special case if original string did not end with eol
273    if encoded[-1] not in '\r\n' and decoded.endswith(eol):
274        decoded = decoded[:-1]
275    return decoded
276
277
278# For convenience and backwards compatibility w/ standard base64 module
279body_decode = decode
280decodestring = decode
281
282
283
284def _unquote_match(match):
285    """Turn a match in the form =AB to the ASCII character with value 0xab"""
286    s = match.group(0)
287    return unquote(s)
288
289
290# Header decoding is done a bit differently
291def header_decode(s):
292    """Decode a string encoded with RFC 2045 MIME header `Q' encoding.
293
294    This function does not parse a full MIME header value encoded with
295    quoted-printable (like =?iso-8859-1?q?Hello_World?=) -- please use
296    the high level email.header class for that functionality.
297    """
298    s = s.replace('_', ' ')
299    return re.sub(r'=[a-fA-F0-9]{2}', _unquote_match, s, flags=re.ASCII)
300