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 7 This module handles the content transfer encoding method defined in RFC 2045 8 to encode US ASCII-like 8-bit data called `quoted-printable'. It is used to 9 safely encode text that is in a character set similar to the 7-bit US ASCII 10 character set, but that includes some 8-bit characters that are normally not 11 allowed in email bodies or headers. 12 13 Quoted-printable is very space-inefficient for encoding binary files; use the 14 email.base64mime module for that instead. 15 16 This module provides an interface to encode and decode both headers and bodies 17 with quoted-printable encoding. 18 19 RFC 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 21 in To:/From:/Cc: etc. fields, as well as Subject: lines. 22 23 This module does not do the line wrapping or end-of-line character 24 conversion necessary for proper internationalized headers; it only 25 does dumb encoding and decoding. To deal with the various line 26 wrapping 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 42 import re 43 import io 44 45 from string import ascii_letters, digits, hexdigits 46 47 CRLF = '\r\n' 48 NL = '\n' 49 EMPTYSTRING = '' 50 51 # Build a mapping of octets to the expansion of that octet. Since we're only 52 # going to have 256 of these things, this isn't terribly inefficient 53 # space-wise. Remember that headers and bodies have different sets of safe 54 # characters. Initialize both maps with the full expansion, and then override 55 # the safe bytes with the more compact form. 56 _QUOPRI_HEADER_MAP = dict((c, '=%02X' % c) for c in range(256)) 57 _QUOPRI_BODY_MAP = _QUOPRI_HEADER_MAP.copy() 58 59 # Safe header bytes which need no encoding. 60 for 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. 66 for c in (b' !"#$%&\'()*+,-./0123456789:;<>' 67 b'?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`' 68 b'abcdefghijklmnopqrstuvwxyz{|}~\t'): 69 _QUOPRI_BODY_MAP[c] = chr(c) 70 71 72 73 # Helpers 74 def 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 79 def 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 84 def 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 97 def 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 107 def _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 118 def 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 123 def quote(c): 124 return '=%02X' % ord(c) 125 126 127 128 def header_encode(header_bytes, charset='iso-8859-1'): 129 """Encode a single header line with quoted-printable (like) encoding. 130 131 Defined in RFC 2045, this `Q' encoding is similar to quoted-printable, but 132 used specifically for email header fields to allow charsets with mostly 7 133 bit characters (and some 8 bit) to remain more or less readable in non-RFC 134 2045 aware mail clients. 135 136 charset names the character set to use in the RFC 2046 header. It 137 defaults to iso-8859-1. 138 """ 139 # Return empty headers as an empty string. 140 if not header_bytes: 141 return '' 142 # Iterate over every byte, encoding if necessary. 143 encoded = [] 144 for octet in header_bytes: 145 encoded.append(_QUOPRI_HEADER_MAP[octet]) 146 # Now add the RFC chrome to each encoded chunk and glue the chunks 147 # together. 148 return '=?%s?q?%s?=' % (charset, EMPTYSTRING.join(encoded)) 149 150 151 class _body_accumulator(io.StringIO): 152 153 def __init__(self, maxlinelen, eol, *args, **kw): 154 super().__init__(*args, **kw) 155 self.eol = eol 156 self.maxlinelen = self.room = maxlinelen 157 158 def write_str(self, s): 159 """Add string s to the accumulated body.""" 160 self.write(s) 161 self.room -= len(s) 162 163 def newline(self): 164 """Write eol, then start new line.""" 165 self.write_str(self.eol) 166 self.room = self.maxlinelen 167 168 def write_soft_break(self): 169 """Write a soft break, then start a new line.""" 170 self.write_str('=') 171 self.newline() 172 173 def write_wrapped(self, s, extra_room=0): 174 """Add a soft line break if needed, then write s.""" 175 if self.room < len(s) + extra_room: 176 self.write_soft_break() 177 self.write_str(s) 178 179 def write_char(self, c, is_last_char): 180 if not is_last_char: 181 # Another character follows on this line, so we must leave 182 # extra room, either for it or a soft break, and whitespace 183 # need not be quoted. 184 self.write_wrapped(c, extra_room=1) 185 elif c not in ' \t': 186 # For this and remaining cases, no more characters follow, 187 # so there is no need to reserve extra room (since a hard 188 # break will immediately follow). 189 self.write_wrapped(c) 190 elif self.room >= 3: 191 # It's a whitespace character at end-of-line, and we have room 192 # for the three-character quoted encoding. 193 self.write(quote(c)) 194 elif self.room == 2: 195 # There's room for the whitespace character and a soft break. 196 self.write(c) 197 self.write_soft_break() 198 else: 199 # There's room only for a soft break. The quoted whitespace 200 # will be the only content on the subsequent line. 201 self.write_soft_break() 202 self.write(quote(c)) 203 204 205 def body_encode(body, maxlinelen=76, eol=NL): 206 """Encode with quoted-printable, wrapping at maxlinelen characters. 207 208 Each line of encoded text will end with eol, which defaults to "\\n". Set 209 this to "\\r\\n" if you will be using the result of this function directly 210 in an email. 211 212 Each line will be wrapped at, at most, maxlinelen characters before the 213 eol string (maxlinelen defaults to 76 characters, the maximum value 214 permitted by RFC 2045). Long lines will have the 'soft line break' 215 quoted-printable character "=" appended to them, so the decoded text will 216 be identical to the original text. 217 218 The minimum maxlinelen is 4 to have room for a quoted character ("=XX") 219 followed by a soft line break. Smaller values will generate a 220 ValueError. 221 222 """ 223 224 if maxlinelen < 4: 225 raise ValueError("maxlinelen must be at least 4") 226 if not body: 227 return body 228 229 # The last line may or may not end in eol, but all other lines do. 230 last_has_eol = (body[-1] in '\r\n') 231 232 # This accumulator will make it easier to build the encoded body. 233 encoded_body = _body_accumulator(maxlinelen, eol) 234 235 lines = body.splitlines() 236 last_line_no = len(lines) - 1 237 for line_no, line in enumerate(lines): 238 last_char_index = len(line) - 1 239 for i, c in enumerate(line): 240 if body_check(ord(c)): 241 c = quote(c) 242 encoded_body.write_char(c, i==last_char_index) 243 # Add an eol if input line had eol. All input lines have eol except 244 # possibly the last one. 245 if line_no < last_line_no or last_has_eol: 246 encoded_body.newline() 247 248 return encoded_body.getvalue() 249 250 251 252 # BAW: I'm not sure if the intent was for the signature of this function to be 253 # the same as base64MIME.decode() or not... 254 def decode(encoded, eol=NL): 255 """Decode a quoted-printable string. 256 257 Lines are separated with eol, which defaults to \\n. 258 """ 259 if not encoded: 260 return encoded 261 # BAW: see comment in encode() above. Again, we're building up the 262 # decoded string with string concatenation, which could be done much more 263 # efficiently. 264 decoded = '' 265 266 for line in encoded.splitlines(): 267 line = line.rstrip() 268 if not line: 269 decoded += eol 270 continue 271 272 i = 0 273 n = len(line) 274 while i < n: 275 c = line[i] 276 if c != '=': 277 decoded += c 278 i += 1 279 # Otherwise, c == "=". Are we at the end of the line? If so, add 280 # a soft line break. 281 elif i+1 == n: 282 i += 1 283 continue 284 # Decode if in form =AB 285 elif i+2 < n and line[i+1] in hexdigits and line[i+2] in hexdigits: 286 decoded += unquote(line[i:i+3]) 287 i += 3 288 # Otherwise, not in form =AB, pass literally 289 else: 290 decoded += c 291 i += 1 292 293 if i == n: 294 decoded += eol 295 # Special case if original string did not end with eol 296 if encoded[-1] not in '\r\n' and decoded.endswith(eol): 297 decoded = decoded[:-1] 298 return decoded 299 300 301 # For convenience and backwards compatibility w/ standard base64 module 302 body_decode = decode 303 decodestring = decode 304 305 306 307 def _unquote_match(match): 308 """Turn a match in the form =AB to the ASCII character with value 0xab""" 309 s = match.group(0) 310 return unquote(s) 311 312 313 # Header decoding is done a bit differently 314 def header_decode(s): 315 """Decode a string encoded with RFC 2045 MIME header `Q' encoding. 316 317 This function does not parse a full MIME header value encoded with 318 quoted-printable (like =?iso-8895-1?q?Hello_World?=) -- please use 319 the high level email.header class for that functionality. 320 """ 321 s = s.replace('_', ' ') 322 return re.sub(r'=[a-fA-F0-9]{2}', _unquote_match, s, flags=re.ASCII) |