| 1 |
# Copyright (C) 2001 Python Software Foundation |
| 2 |
# Author: Ben Gertzfield |
| 3 |
# Contact: [email protected] |
| 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 |
|
| 44 |
from string import ascii_letters, digits, hexdigits |
| 45 |
|
| 46 |
CRLF = '\r\n' |
| 47 |
NL = '\n' |
| 48 |
EMPTYSTRING = '' |
| 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. |
| 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 _QUOPRI_MAP[ord(c)] |
| 125 |
|
| 126 |
|
| 127 |
def 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[:] |
| 149 |
for c in b'\r\n': |
| 150 |
_QUOPRI_BODY_ENCODE_MAP[c] = chr(c) |
| 151 |
del c |
| 152 |
|
| 153 |
def body_encode(body, maxlinelen=76, eol=NL): |
| 154 |
"""Encode with quoted-printable, wrapping at maxlinelen characters. |
| 155 |
|
| 156 |
Each line of encoded text will end with eol, which defaults to "\\n". Set |
| 157 |
this to "\\r\\n" if you will be using the result of this function directly |
| 158 |
in an email. |
| 159 |
|
| 160 |
Each line will be wrapped at, at most, maxlinelen characters before the |
| 161 |
eol string (maxlinelen defaults to 76 characters, the maximum value |
| 162 |
permitted by RFC 2045). Long lines will have the 'soft line break' |
| 163 |
quoted-printable character "=" appended to them, so the decoded text will |
| 164 |
be identical to the original text. |
| 165 |
|
| 166 |
The minimum maxlinelen is 4 to have room for a quoted character ("=XX") |
| 167 |
followed by a soft line break. Smaller values will generate a |
| 168 |
ValueError. |
| 169 |
|
| 170 |
""" |
| 171 |
|
| 172 |
if maxlinelen < 4: |
| 173 |
raise ValueError("maxlinelen must be at least 4") |
| 174 |
if not body: |
| 175 |
return body |
| 176 |
|
| 177 |
# quote special characters |
| 178 |
body = body.translate(_QUOPRI_BODY_ENCODE_MAP) |
| 179 |
|
| 180 |
soft_break = '=' + eol |
| 181 |
# leave space for the '=' at the end of a line |
| 182 |
maxlinelen1 = maxlinelen - 1 |
| 183 |
|
| 184 |
encoded_body = [] |
| 185 |
append = encoded_body.append |
| 186 |
|
| 187 |
for line in body.splitlines(): |
| 188 |
# break up the line into pieces no longer than maxlinelen - 1 |
| 189 |
start = 0 |
| 190 |
laststart = len(line) - 1 - maxlinelen |
| 191 |
while start <= laststart: |
| 192 |
stop = start + maxlinelen1 |
| 193 |
# make sure we don't break up an escape sequence |
| 194 |
if line[stop - 2] == '=': |
| 195 |
append(line[start:stop - 1]) |
| 196 |
start = stop - 2 |
| 197 |
elif line[stop - 1] == '=': |
| 198 |
append(line[start:stop]) |
| 199 |
start = stop - 1 |
| 200 |
else: |
| 201 |
append(line[start:stop] + '=') |
| 202 |
start = stop |
| 203 |
|
| 204 |
# handle rest of line, special case if line ends in whitespace |
| 205 |
if line and line[-1] in ' \t': |
| 206 |
room = start - laststart |
| 207 |
if room >= 3: |
| 208 |
# It's a whitespace character at end-of-line, and we have room |
| 209 |
# for the three-character quoted encoding. |
| 210 |
q = quote(line[-1]) |
| 211 |
elif room == 2: |
| 212 |
# There's room for the whitespace character and a soft break. |
| 213 |
q = line[-1] + soft_break |
| 214 |
else: |
| 215 |
# There's room only for a soft break. The quoted whitespace |
| 216 |
# will be the only content on the subsequent line. |
| 217 |
q = soft_break + quote(line[-1]) |
| 218 |
append(line[start:-1] + q) |
| 219 |
else: |
| 220 |
append(line[start:]) |
| 221 |
|
| 222 |
# add back final newline if present |
| 223 |
if body[-1] in CRLF: |
| 224 |
append('') |
| 225 |
|
| 226 |
return eol.join(encoded_body) |
| 227 |
|
| 228 |
|
| 229 |
|
| 230 |
# BAW: I'm not sure if the intent was for the signature of this function to be |
| 231 |
# the same as base64MIME.decode() or not... |
| 232 |
def decode(encoded, eol=NL): |
| 233 |
"""Decode a quoted-printable string. |
| 234 |
|
| 235 |
Lines are separated with eol, which defaults to \\n. |
| 236 |
""" |
| 237 |
if not encoded: |
| 238 |
return encoded |
| 239 |
# BAW: see comment in encode() above. Again, we're building up the |
| 240 |
# decoded string with string concatenation, which could be done much more |
| 241 |
# efficiently. |
| 242 |
decoded = '' |
| 243 |
|
| 244 |
for line in encoded.splitlines(): |
| 245 |
line = line.rstrip() |
| 246 |
if not line: |
| 247 |
decoded += eol |
| 248 |
continue |
| 249 |
|
| 250 |
i = 0 |
| 251 |
n = len(line) |
| 252 |
while i < n: |
| 253 |
c = line[i] |
| 254 |
if c != '=': |
| 255 |
decoded += c |
| 256 |
i += 1 |
| 257 |
# Otherwise, c == "=". Are we at the end of the line? If so, add |
| 258 |
# a soft line break. |
| 259 |
elif i+1 == n: |
| 260 |
i += 1 |
| 261 |
continue |
| 262 |
# Decode if in form =AB |
| 263 |
elif i+2 < n and line[i+1] in hexdigits and line[i+2] in hexdigits: |
| 264 |
decoded += unquote(line[i:i+3]) |
| 265 |
i += 3 |
| 266 |
# Otherwise, not in form =AB, pass literally |
| 267 |
else: |
| 268 |
decoded += c |
| 269 |
i += 1 |
| 270 |
|
| 271 |
if i == n: |
| 272 |
decoded += eol |
| 273 |
# Special case if original string did not end with eol |
| 274 |
if encoded[-1] not in '\r\n' and decoded.endswith(eol): |
| 275 |
decoded = decoded[:-len(eol)] |
| 276 |
return decoded |
| 277 |
|
| 278 |
|
| 279 |
# For convenience and backwards compatibility w/ standard base64 module |
| 280 |
body_decode = decode |
| 281 |
decodestring = decode |
| 282 |
|
| 283 |
|
| 284 |
|
| 285 |
def _unquote_match(match): |
| 286 |
"""Turn a match in the form =AB to the ASCII character with value 0xab""" |
| 287 |
s = match.group(0) |
| 288 |
return unquote(s) |
| 289 |
|
| 290 |
|
| 291 |
# Header decoding is done a bit differently |
| 292 |
def header_decode(s): |
| 293 |
"""Decode a string encoded with RFC 2045 MIME header 'Q' encoding. |
| 294 |
|
| 295 |
This function does not parse a full MIME header value encoded with |
| 296 |
quoted-printable (like =?iso-8859-1?q?Hello_World?=) -- please use |
| 297 |
the high level email.header class for that functionality. |
| 298 |
""" |
| 299 |
s = s.replace('_', ' ') |
| 300 |
return re.sub(r'=[a-fA-F0-9]{2}', _unquote_match, s, flags=re.ASCII) |