Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/email/charset.py @ 68:5028fdace37b

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 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 # Copyright (C) 2001-2007 Python Software Foundation
jpayne@68 2 # Author: Ben Gertzfield, Barry Warsaw
jpayne@68 3 # Contact: email-sig@python.org
jpayne@68 4
jpayne@68 5 __all__ = [
jpayne@68 6 'Charset',
jpayne@68 7 'add_alias',
jpayne@68 8 'add_charset',
jpayne@68 9 'add_codec',
jpayne@68 10 ]
jpayne@68 11
jpayne@68 12 from functools import partial
jpayne@68 13
jpayne@68 14 import email.base64mime
jpayne@68 15 import email.quoprimime
jpayne@68 16
jpayne@68 17 from email import errors
jpayne@68 18 from email.encoders import encode_7or8bit
jpayne@68 19
jpayne@68 20
jpayne@68 21
jpayne@68 22 # Flags for types of header encodings
jpayne@68 23 QP = 1 # Quoted-Printable
jpayne@68 24 BASE64 = 2 # Base64
jpayne@68 25 SHORTEST = 3 # the shorter of QP and base64, but only for headers
jpayne@68 26
jpayne@68 27 # In "=?charset?q?hello_world?=", the =?, ?q?, and ?= add up to 7
jpayne@68 28 RFC2047_CHROME_LEN = 7
jpayne@68 29
jpayne@68 30 DEFAULT_CHARSET = 'us-ascii'
jpayne@68 31 UNKNOWN8BIT = 'unknown-8bit'
jpayne@68 32 EMPTYSTRING = ''
jpayne@68 33
jpayne@68 34
jpayne@68 35
jpayne@68 36 # Defaults
jpayne@68 37 CHARSETS = {
jpayne@68 38 # input header enc body enc output conv
jpayne@68 39 'iso-8859-1': (QP, QP, None),
jpayne@68 40 'iso-8859-2': (QP, QP, None),
jpayne@68 41 'iso-8859-3': (QP, QP, None),
jpayne@68 42 'iso-8859-4': (QP, QP, None),
jpayne@68 43 # iso-8859-5 is Cyrillic, and not especially used
jpayne@68 44 # iso-8859-6 is Arabic, also not particularly used
jpayne@68 45 # iso-8859-7 is Greek, QP will not make it readable
jpayne@68 46 # iso-8859-8 is Hebrew, QP will not make it readable
jpayne@68 47 'iso-8859-9': (QP, QP, None),
jpayne@68 48 'iso-8859-10': (QP, QP, None),
jpayne@68 49 # iso-8859-11 is Thai, QP will not make it readable
jpayne@68 50 'iso-8859-13': (QP, QP, None),
jpayne@68 51 'iso-8859-14': (QP, QP, None),
jpayne@68 52 'iso-8859-15': (QP, QP, None),
jpayne@68 53 'iso-8859-16': (QP, QP, None),
jpayne@68 54 'windows-1252':(QP, QP, None),
jpayne@68 55 'viscii': (QP, QP, None),
jpayne@68 56 'us-ascii': (None, None, None),
jpayne@68 57 'big5': (BASE64, BASE64, None),
jpayne@68 58 'gb2312': (BASE64, BASE64, None),
jpayne@68 59 'euc-jp': (BASE64, None, 'iso-2022-jp'),
jpayne@68 60 'shift_jis': (BASE64, None, 'iso-2022-jp'),
jpayne@68 61 'iso-2022-jp': (BASE64, None, None),
jpayne@68 62 'koi8-r': (BASE64, BASE64, None),
jpayne@68 63 'utf-8': (SHORTEST, BASE64, 'utf-8'),
jpayne@68 64 }
jpayne@68 65
jpayne@68 66 # Aliases for other commonly-used names for character sets. Map
jpayne@68 67 # them to the real ones used in email.
jpayne@68 68 ALIASES = {
jpayne@68 69 'latin_1': 'iso-8859-1',
jpayne@68 70 'latin-1': 'iso-8859-1',
jpayne@68 71 'latin_2': 'iso-8859-2',
jpayne@68 72 'latin-2': 'iso-8859-2',
jpayne@68 73 'latin_3': 'iso-8859-3',
jpayne@68 74 'latin-3': 'iso-8859-3',
jpayne@68 75 'latin_4': 'iso-8859-4',
jpayne@68 76 'latin-4': 'iso-8859-4',
jpayne@68 77 'latin_5': 'iso-8859-9',
jpayne@68 78 'latin-5': 'iso-8859-9',
jpayne@68 79 'latin_6': 'iso-8859-10',
jpayne@68 80 'latin-6': 'iso-8859-10',
jpayne@68 81 'latin_7': 'iso-8859-13',
jpayne@68 82 'latin-7': 'iso-8859-13',
jpayne@68 83 'latin_8': 'iso-8859-14',
jpayne@68 84 'latin-8': 'iso-8859-14',
jpayne@68 85 'latin_9': 'iso-8859-15',
jpayne@68 86 'latin-9': 'iso-8859-15',
jpayne@68 87 'latin_10':'iso-8859-16',
jpayne@68 88 'latin-10':'iso-8859-16',
jpayne@68 89 'cp949': 'ks_c_5601-1987',
jpayne@68 90 'euc_jp': 'euc-jp',
jpayne@68 91 'euc_kr': 'euc-kr',
jpayne@68 92 'ascii': 'us-ascii',
jpayne@68 93 }
jpayne@68 94
jpayne@68 95
jpayne@68 96 # Map charsets to their Unicode codec strings.
jpayne@68 97 CODEC_MAP = {
jpayne@68 98 'gb2312': 'eucgb2312_cn',
jpayne@68 99 'big5': 'big5_tw',
jpayne@68 100 # Hack: We don't want *any* conversion for stuff marked us-ascii, as all
jpayne@68 101 # sorts of garbage might be sent to us in the guise of 7-bit us-ascii.
jpayne@68 102 # Let that stuff pass through without conversion to/from Unicode.
jpayne@68 103 'us-ascii': None,
jpayne@68 104 }
jpayne@68 105
jpayne@68 106
jpayne@68 107
jpayne@68 108 # Convenience functions for extending the above mappings
jpayne@68 109 def add_charset(charset, header_enc=None, body_enc=None, output_charset=None):
jpayne@68 110 """Add character set properties to the global registry.
jpayne@68 111
jpayne@68 112 charset is the input character set, and must be the canonical name of a
jpayne@68 113 character set.
jpayne@68 114
jpayne@68 115 Optional header_enc and body_enc is either Charset.QP for
jpayne@68 116 quoted-printable, Charset.BASE64 for base64 encoding, Charset.SHORTEST for
jpayne@68 117 the shortest of qp or base64 encoding, or None for no encoding. SHORTEST
jpayne@68 118 is only valid for header_enc. It describes how message headers and
jpayne@68 119 message bodies in the input charset are to be encoded. Default is no
jpayne@68 120 encoding.
jpayne@68 121
jpayne@68 122 Optional output_charset is the character set that the output should be
jpayne@68 123 in. Conversions will proceed from input charset, to Unicode, to the
jpayne@68 124 output charset when the method Charset.convert() is called. The default
jpayne@68 125 is to output in the same character set as the input.
jpayne@68 126
jpayne@68 127 Both input_charset and output_charset must have Unicode codec entries in
jpayne@68 128 the module's charset-to-codec mapping; use add_codec(charset, codecname)
jpayne@68 129 to add codecs the module does not know about. See the codecs module's
jpayne@68 130 documentation for more information.
jpayne@68 131 """
jpayne@68 132 if body_enc == SHORTEST:
jpayne@68 133 raise ValueError('SHORTEST not allowed for body_enc')
jpayne@68 134 CHARSETS[charset] = (header_enc, body_enc, output_charset)
jpayne@68 135
jpayne@68 136
jpayne@68 137 def add_alias(alias, canonical):
jpayne@68 138 """Add a character set alias.
jpayne@68 139
jpayne@68 140 alias is the alias name, e.g. latin-1
jpayne@68 141 canonical is the character set's canonical name, e.g. iso-8859-1
jpayne@68 142 """
jpayne@68 143 ALIASES[alias] = canonical
jpayne@68 144
jpayne@68 145
jpayne@68 146 def add_codec(charset, codecname):
jpayne@68 147 """Add a codec that map characters in the given charset to/from Unicode.
jpayne@68 148
jpayne@68 149 charset is the canonical name of a character set. codecname is the name
jpayne@68 150 of a Python codec, as appropriate for the second argument to the unicode()
jpayne@68 151 built-in, or to the encode() method of a Unicode string.
jpayne@68 152 """
jpayne@68 153 CODEC_MAP[charset] = codecname
jpayne@68 154
jpayne@68 155
jpayne@68 156
jpayne@68 157 # Convenience function for encoding strings, taking into account
jpayne@68 158 # that they might be unknown-8bit (ie: have surrogate-escaped bytes)
jpayne@68 159 def _encode(string, codec):
jpayne@68 160 if codec == UNKNOWN8BIT:
jpayne@68 161 return string.encode('ascii', 'surrogateescape')
jpayne@68 162 else:
jpayne@68 163 return string.encode(codec)
jpayne@68 164
jpayne@68 165
jpayne@68 166
jpayne@68 167 class Charset:
jpayne@68 168 """Map character sets to their email properties.
jpayne@68 169
jpayne@68 170 This class provides information about the requirements imposed on email
jpayne@68 171 for a specific character set. It also provides convenience routines for
jpayne@68 172 converting between character sets, given the availability of the
jpayne@68 173 applicable codecs. Given a character set, it will do its best to provide
jpayne@68 174 information on how to use that character set in an email in an
jpayne@68 175 RFC-compliant way.
jpayne@68 176
jpayne@68 177 Certain character sets must be encoded with quoted-printable or base64
jpayne@68 178 when used in email headers or bodies. Certain character sets must be
jpayne@68 179 converted outright, and are not allowed in email. Instances of this
jpayne@68 180 module expose the following information about a character set:
jpayne@68 181
jpayne@68 182 input_charset: The initial character set specified. Common aliases
jpayne@68 183 are converted to their `official' email names (e.g. latin_1
jpayne@68 184 is converted to iso-8859-1). Defaults to 7-bit us-ascii.
jpayne@68 185
jpayne@68 186 header_encoding: If the character set must be encoded before it can be
jpayne@68 187 used in an email header, this attribute will be set to
jpayne@68 188 Charset.QP (for quoted-printable), Charset.BASE64 (for
jpayne@68 189 base64 encoding), or Charset.SHORTEST for the shortest of
jpayne@68 190 QP or BASE64 encoding. Otherwise, it will be None.
jpayne@68 191
jpayne@68 192 body_encoding: Same as header_encoding, but describes the encoding for the
jpayne@68 193 mail message's body, which indeed may be different than the
jpayne@68 194 header encoding. Charset.SHORTEST is not allowed for
jpayne@68 195 body_encoding.
jpayne@68 196
jpayne@68 197 output_charset: Some character sets must be converted before they can be
jpayne@68 198 used in email headers or bodies. If the input_charset is
jpayne@68 199 one of them, this attribute will contain the name of the
jpayne@68 200 charset output will be converted to. Otherwise, it will
jpayne@68 201 be None.
jpayne@68 202
jpayne@68 203 input_codec: The name of the Python codec used to convert the
jpayne@68 204 input_charset to Unicode. If no conversion codec is
jpayne@68 205 necessary, this attribute will be None.
jpayne@68 206
jpayne@68 207 output_codec: The name of the Python codec used to convert Unicode
jpayne@68 208 to the output_charset. If no conversion codec is necessary,
jpayne@68 209 this attribute will have the same value as the input_codec.
jpayne@68 210 """
jpayne@68 211 def __init__(self, input_charset=DEFAULT_CHARSET):
jpayne@68 212 # RFC 2046, $4.1.2 says charsets are not case sensitive. We coerce to
jpayne@68 213 # unicode because its .lower() is locale insensitive. If the argument
jpayne@68 214 # is already a unicode, we leave it at that, but ensure that the
jpayne@68 215 # charset is ASCII, as the standard (RFC XXX) requires.
jpayne@68 216 try:
jpayne@68 217 if isinstance(input_charset, str):
jpayne@68 218 input_charset.encode('ascii')
jpayne@68 219 else:
jpayne@68 220 input_charset = str(input_charset, 'ascii')
jpayne@68 221 except UnicodeError:
jpayne@68 222 raise errors.CharsetError(input_charset)
jpayne@68 223 input_charset = input_charset.lower()
jpayne@68 224 # Set the input charset after filtering through the aliases
jpayne@68 225 self.input_charset = ALIASES.get(input_charset, input_charset)
jpayne@68 226 # We can try to guess which encoding and conversion to use by the
jpayne@68 227 # charset_map dictionary. Try that first, but let the user override
jpayne@68 228 # it.
jpayne@68 229 henc, benc, conv = CHARSETS.get(self.input_charset,
jpayne@68 230 (SHORTEST, BASE64, None))
jpayne@68 231 if not conv:
jpayne@68 232 conv = self.input_charset
jpayne@68 233 # Set the attributes, allowing the arguments to override the default.
jpayne@68 234 self.header_encoding = henc
jpayne@68 235 self.body_encoding = benc
jpayne@68 236 self.output_charset = ALIASES.get(conv, conv)
jpayne@68 237 # Now set the codecs. If one isn't defined for input_charset,
jpayne@68 238 # guess and try a Unicode codec with the same name as input_codec.
jpayne@68 239 self.input_codec = CODEC_MAP.get(self.input_charset,
jpayne@68 240 self.input_charset)
jpayne@68 241 self.output_codec = CODEC_MAP.get(self.output_charset,
jpayne@68 242 self.output_charset)
jpayne@68 243
jpayne@68 244 def __repr__(self):
jpayne@68 245 return self.input_charset.lower()
jpayne@68 246
jpayne@68 247 def __eq__(self, other):
jpayne@68 248 return str(self) == str(other).lower()
jpayne@68 249
jpayne@68 250 def get_body_encoding(self):
jpayne@68 251 """Return the content-transfer-encoding used for body encoding.
jpayne@68 252
jpayne@68 253 This is either the string `quoted-printable' or `base64' depending on
jpayne@68 254 the encoding used, or it is a function in which case you should call
jpayne@68 255 the function with a single argument, the Message object being
jpayne@68 256 encoded. The function should then set the Content-Transfer-Encoding
jpayne@68 257 header itself to whatever is appropriate.
jpayne@68 258
jpayne@68 259 Returns "quoted-printable" if self.body_encoding is QP.
jpayne@68 260 Returns "base64" if self.body_encoding is BASE64.
jpayne@68 261 Returns conversion function otherwise.
jpayne@68 262 """
jpayne@68 263 assert self.body_encoding != SHORTEST
jpayne@68 264 if self.body_encoding == QP:
jpayne@68 265 return 'quoted-printable'
jpayne@68 266 elif self.body_encoding == BASE64:
jpayne@68 267 return 'base64'
jpayne@68 268 else:
jpayne@68 269 return encode_7or8bit
jpayne@68 270
jpayne@68 271 def get_output_charset(self):
jpayne@68 272 """Return the output character set.
jpayne@68 273
jpayne@68 274 This is self.output_charset if that is not None, otherwise it is
jpayne@68 275 self.input_charset.
jpayne@68 276 """
jpayne@68 277 return self.output_charset or self.input_charset
jpayne@68 278
jpayne@68 279 def header_encode(self, string):
jpayne@68 280 """Header-encode a string by converting it first to bytes.
jpayne@68 281
jpayne@68 282 The type of encoding (base64 or quoted-printable) will be based on
jpayne@68 283 this charset's `header_encoding`.
jpayne@68 284
jpayne@68 285 :param string: A unicode string for the header. It must be possible
jpayne@68 286 to encode this string to bytes using the character set's
jpayne@68 287 output codec.
jpayne@68 288 :return: The encoded string, with RFC 2047 chrome.
jpayne@68 289 """
jpayne@68 290 codec = self.output_codec or 'us-ascii'
jpayne@68 291 header_bytes = _encode(string, codec)
jpayne@68 292 # 7bit/8bit encodings return the string unchanged (modulo conversions)
jpayne@68 293 encoder_module = self._get_encoder(header_bytes)
jpayne@68 294 if encoder_module is None:
jpayne@68 295 return string
jpayne@68 296 return encoder_module.header_encode(header_bytes, codec)
jpayne@68 297
jpayne@68 298 def header_encode_lines(self, string, maxlengths):
jpayne@68 299 """Header-encode a string by converting it first to bytes.
jpayne@68 300
jpayne@68 301 This is similar to `header_encode()` except that the string is fit
jpayne@68 302 into maximum line lengths as given by the argument.
jpayne@68 303
jpayne@68 304 :param string: A unicode string for the header. It must be possible
jpayne@68 305 to encode this string to bytes using the character set's
jpayne@68 306 output codec.
jpayne@68 307 :param maxlengths: Maximum line length iterator. Each element
jpayne@68 308 returned from this iterator will provide the next maximum line
jpayne@68 309 length. This parameter is used as an argument to built-in next()
jpayne@68 310 and should never be exhausted. The maximum line lengths should
jpayne@68 311 not count the RFC 2047 chrome. These line lengths are only a
jpayne@68 312 hint; the splitter does the best it can.
jpayne@68 313 :return: Lines of encoded strings, each with RFC 2047 chrome.
jpayne@68 314 """
jpayne@68 315 # See which encoding we should use.
jpayne@68 316 codec = self.output_codec or 'us-ascii'
jpayne@68 317 header_bytes = _encode(string, codec)
jpayne@68 318 encoder_module = self._get_encoder(header_bytes)
jpayne@68 319 encoder = partial(encoder_module.header_encode, charset=codec)
jpayne@68 320 # Calculate the number of characters that the RFC 2047 chrome will
jpayne@68 321 # contribute to each line.
jpayne@68 322 charset = self.get_output_charset()
jpayne@68 323 extra = len(charset) + RFC2047_CHROME_LEN
jpayne@68 324 # Now comes the hard part. We must encode bytes but we can't split on
jpayne@68 325 # bytes because some character sets are variable length and each
jpayne@68 326 # encoded word must stand on its own. So the problem is you have to
jpayne@68 327 # encode to bytes to figure out this word's length, but you must split
jpayne@68 328 # on characters. This causes two problems: first, we don't know how
jpayne@68 329 # many octets a specific substring of unicode characters will get
jpayne@68 330 # encoded to, and second, we don't know how many ASCII characters
jpayne@68 331 # those octets will get encoded to. Unless we try it. Which seems
jpayne@68 332 # inefficient. In the interest of being correct rather than fast (and
jpayne@68 333 # in the hope that there will be few encoded headers in any such
jpayne@68 334 # message), brute force it. :(
jpayne@68 335 lines = []
jpayne@68 336 current_line = []
jpayne@68 337 maxlen = next(maxlengths) - extra
jpayne@68 338 for character in string:
jpayne@68 339 current_line.append(character)
jpayne@68 340 this_line = EMPTYSTRING.join(current_line)
jpayne@68 341 length = encoder_module.header_length(_encode(this_line, charset))
jpayne@68 342 if length > maxlen:
jpayne@68 343 # This last character doesn't fit so pop it off.
jpayne@68 344 current_line.pop()
jpayne@68 345 # Does nothing fit on the first line?
jpayne@68 346 if not lines and not current_line:
jpayne@68 347 lines.append(None)
jpayne@68 348 else:
jpayne@68 349 separator = (' ' if lines else '')
jpayne@68 350 joined_line = EMPTYSTRING.join(current_line)
jpayne@68 351 header_bytes = _encode(joined_line, codec)
jpayne@68 352 lines.append(encoder(header_bytes))
jpayne@68 353 current_line = [character]
jpayne@68 354 maxlen = next(maxlengths) - extra
jpayne@68 355 joined_line = EMPTYSTRING.join(current_line)
jpayne@68 356 header_bytes = _encode(joined_line, codec)
jpayne@68 357 lines.append(encoder(header_bytes))
jpayne@68 358 return lines
jpayne@68 359
jpayne@68 360 def _get_encoder(self, header_bytes):
jpayne@68 361 if self.header_encoding == BASE64:
jpayne@68 362 return email.base64mime
jpayne@68 363 elif self.header_encoding == QP:
jpayne@68 364 return email.quoprimime
jpayne@68 365 elif self.header_encoding == SHORTEST:
jpayne@68 366 len64 = email.base64mime.header_length(header_bytes)
jpayne@68 367 lenqp = email.quoprimime.header_length(header_bytes)
jpayne@68 368 if len64 < lenqp:
jpayne@68 369 return email.base64mime
jpayne@68 370 else:
jpayne@68 371 return email.quoprimime
jpayne@68 372 else:
jpayne@68 373 return None
jpayne@68 374
jpayne@68 375 def body_encode(self, string):
jpayne@68 376 """Body-encode a string by converting it first to bytes.
jpayne@68 377
jpayne@68 378 The type of encoding (base64 or quoted-printable) will be based on
jpayne@68 379 self.body_encoding. If body_encoding is None, we assume the
jpayne@68 380 output charset is a 7bit encoding, so re-encoding the decoded
jpayne@68 381 string using the ascii codec produces the correct string version
jpayne@68 382 of the content.
jpayne@68 383 """
jpayne@68 384 if not string:
jpayne@68 385 return string
jpayne@68 386 if self.body_encoding is BASE64:
jpayne@68 387 if isinstance(string, str):
jpayne@68 388 string = string.encode(self.output_charset)
jpayne@68 389 return email.base64mime.body_encode(string)
jpayne@68 390 elif self.body_encoding is QP:
jpayne@68 391 # quopromime.body_encode takes a string, but operates on it as if
jpayne@68 392 # it were a list of byte codes. For a (minimal) history on why
jpayne@68 393 # this is so, see changeset 0cf700464177. To correctly encode a
jpayne@68 394 # character set, then, we must turn it into pseudo bytes via the
jpayne@68 395 # latin1 charset, which will encode any byte as a single code point
jpayne@68 396 # between 0 and 255, which is what body_encode is expecting.
jpayne@68 397 if isinstance(string, str):
jpayne@68 398 string = string.encode(self.output_charset)
jpayne@68 399 string = string.decode('latin1')
jpayne@68 400 return email.quoprimime.body_encode(string)
jpayne@68 401 else:
jpayne@68 402 if isinstance(string, str):
jpayne@68 403 string = string.encode(self.output_charset).decode('ascii')
jpayne@68 404 return string