Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/email/quoprimime.py @ 69:33d812a61356

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