Lib/email/message.py

   1 # Copyright (C) 2001-2006 Python Software Foundation
   2 # Author: Barry Warsaw
   3 # Contact: email-sig@python.org
   4
   5 """Basic message object for the email package object model."""
   6
   7 __all__ = ['Message']
   8
   9 import re
  10 import uu
  11 import binascii
  12 import warnings
  13 from cStringIO import StringIO
  14
  15 # Intrapackage imports
  16 import email.charset
  17 from email import utils
  18 from email import errors
  19
  20 SEMISPACE = '; '
  21
  22 # Regular expression used to split header parameters.  BAW: this may be too
  23 # simple.  It isn't strictly RFC 2045 (section 5.1) compliant, but it catches
  24 # most headers found in the wild.  We may eventually need a full fledged
  25 # parser eventually.
  26 paramre = re.compile(r'\s*;\s*')
  27 # Regular expression that matches `special' characters in parameters, the
  28 # existance of which force quoting of the parameter value.
  29 tspecials = re.compile(r'[ \(\)<>@,;:\\"/\[\]\?=]')
  30
  31
  32 \f
  33 # Helper functions
  34 def _formatparam(param, value=None, quote=True):
  35     """Convenience function to format and return a key=value pair.
  36
  37     This will quote the value if needed or if quote is true.
  38     """
  39     if value is not None and len(value) > 0:
  40         # A tuple is used for RFC 2231 encoded parameter values where items
  41         # are (charset, language, value).  charset is a string, not a Charset
  42         # instance.
  43         if isinstance(value, tuple):
  44             # Encode as per RFC 2231
  45             param += '*'
  46             value = utils.encode_rfc2231(value[2], value[0], value[1])
  47         # BAW: Please check this.  I think that if quote is set it should
  48         # force quoting even if not necessary.
  49         if quote or tspecials.search(value):
  50             return '%s="%s"' % (param, utils.quote(value))
  51         else:
  52             return '%s=%s' % (param, value)
  53     else:
  54         return param
  55
  56 def _parseparam(s):
  57     plist = []
  58     while s[:1] == ';':
  59         s = s[1:]
  60         end = s.find(';')
  61         while end > 0 and s.count('"', 0, end) % 2:
  62             end = s.find(';', end + 1)
  63         if end < 0:
  64             end = len(s)
  65         f = s[:end]
  66         if '=' in f:
  67             i = f.index('=')
  68             f = f[:i].strip().lower() + '=' + f[i+1:].strip()
  69         plist.append(f.strip())
  70         s = s[end:]
  71     return plist
  72
  73
  74 def _unquotevalue(value):
  75     # This is different than utils.collapse_rfc2231_value() because it doesn't
  76     # try to convert the value to a unicode.  Message.get_param() and
  77     # Message.get_params() are both currently defined to return the tuple in
  78     # the face of RFC 2231 parameters.
  79     if isinstance(value, tuple):
  80         return value[0], value[1], utils.unquote(value[2])
  81     else:
  82         return utils.unquote(value)
  83
  84
  85 \f
  86 class Message:
  87     """Basic message object.
  88
  89     A message object is defined as something that has a bunch of RFC 2822
  90     headers and a payload.  It may optionally have an envelope header
  91     (a.k.a. Unix-From or From_ header).  If the message is a container (i.e. a
  92     multipart or a message/rfc822), then the payload is a list of Message
  93     objects, otherwise it is a string.
  94
  95     Message objects implement part of the `mapping' interface, which assumes
  96     there is exactly one occurrance of the header per message.  Some headers
  97     do in fact appear multiple times (e.g. Received) and for those headers,
  98     you must use the explicit API to set or get all the headers.  Not all of
  99     the mapping methods are implemented.
 100     """
 101     def __init__(self):
 102         self._headers = []
 103         self._unixfrom = None
 104         self._payload = None
 105         self._charset = None
 106         # Defaults for multipart messages
 107         self.preamble = self.epilogue = None
 108         self.defects = []
 109         # Default content type
 110         self._default_type = 'text/plain'
 111
 112     def __str__(self):
 113         """Return the entire formatted message as a string.
 114         This includes the headers, body, and envelope header.
 115         """
 116         return self.as_string(unixfrom=True)
 117
 118     def as_string(self, unixfrom=False):
 119         """Return the entire formatted message as a string.
 120         Optional `unixfrom' when True, means include the Unix From_ envelope
 121         header.
 122
 123         This is a convenience method and may not generate the message exactly
 124         as you intend because by default it mangles lines that begin with
 125         "From ".  For more flexibility, use the flatten() method of a
 126         Generator instance.
 127         """
 128         from email.Generator import Generator
 129         fp = StringIO()
 130         g = Generator(fp)
 131         g.flatten(self, unixfrom=unixfrom)
 132         return fp.getvalue()
 133
 134     def is_multipart(self):
 135         """Return True if the message consists of multiple parts."""
 136         return isinstance(self._payload, list)
 137
 138     #
 139     # Unix From_ line
 140     #
 141     def set_unixfrom(self, unixfrom):
 142         self._unixfrom = unixfrom
 143
 144     def get_unixfrom(self):
 145         return self._unixfrom
 146
 147     #
 148     # Payload manipulation.
 149     #
 150     def attach(self, payload):
 151         """Add the given payload to the current payload.
 152
 153         The current payload will always be a list of objects after this method
 154         is called.  If you want to set the payload to a scalar object, use
 155         set_payload() instead.
 156         """
 157         if self._payload is None:
 158             self._payload = [payload]
 159         else:
 160             self._payload.append(payload)
 161
 162     def get_payload(self, i=None, decode=False):
 163         """Return a reference to the payload.
 164
 165         The payload will either be a list object or a string.  If you mutate
 166         the list object, you modify the message's payload in place.  Optional
 167         i returns that index into the payload.
 168
 169         Optional decode is a flag indicating whether the payload should be
 170         decoded or not, according to the Content-Transfer-Encoding header
 171         (default is False).
 172
 173         When True and the message is not a multipart, the payload will be
 174         decoded if this header's value is `quoted-printable' or `base64'.  If
 175         some other encoding is used, or the header is missing, or if the
 176         payload has bogus data (i.e. bogus base64 or uuencoded data), the
 177         payload is returned as-is.
 178
 179         If the message is a multipart and the decode flag is True, then None
 180         is returned.
 181         """
 182         if i is None:
 183             payload = self._payload
 184         elif not isinstance(self._payload, list):
 185             raise TypeError('Expected list, got %s' % type(self._payload))
 186         else:
 187             payload = self._payload[i]
 188         if decode:
 189             if self.is_multipart():
 190                 return None
 191             cte = self.get('content-transfer-encoding', '').lower()
 192             if cte == 'quoted-printable':
 193                 return utils._qdecode(payload)
 194             elif cte == 'base64':
 195                 try:
 196                     return utils._bdecode(payload)
 197                 except binascii.Error:
 198                     # Incorrect padding
 199                     return payload
 200             elif cte in ('x-uuencode', 'uuencode', 'uue', 'x-uue'):
 201                 sfp = StringIO()
 202                 try:
 203                     uu.decode(StringIO(payload+'\n'), sfp, quiet=True)
 204                     payload = sfp.getvalue()
 205                 except uu.Error:
 206                     # Some decoding problem
 207                     return payload
 208         # Everything else, including encodings with 8bit or 7bit are returned
 209         # unchanged.
 210         return payload
 211
 212     def set_payload(self, payload, charset=None):
 213         """Set the payload to the given value.
 214
 215         Optional charset sets the message's default character set.  See
 216         set_charset() for details.
 217         """
 218         self._payload = payload
 219         if charset is not None:
 220             self.set_charset(charset)
 221
 222     def set_charset(self, charset):
 223         """Set the charset of the payload to a given character set.
 224
 225         charset can be a Charset instance, a string naming a character set, or
 226         None.  If it is a string it will be converted to a Charset instance.
 227         If charset is None, the charset parameter will be removed from the
 228         Content-Type field.  Anything else will generate a TypeError.
 229
 230         The message will be assumed to be of type text/* encoded with
 231         charset.input_charset.  It will be converted to charset.output_charset
 232         and encoded properly, if needed, when generating the plain text
 233         representation of the message.  MIME headers (MIME-Version,
 234         Content-Type, Content-Transfer-Encoding) will be added as needed.
 235
 236         """
 237         if charset is None:
 238             self.del_param('charset')
 239             self._charset = None
 240             return
 241         if isinstance(charset, basestring):
 242             charset = email.charset.Charset(charset)
 243         if not isinstance(charset, email.charset.Charset):
 244             raise TypeError(charset)
 245         # BAW: should we accept strings that can serve as arguments to the
 246         # Charset constructor?
 247         self._charset = charset
 248         if not self.has_key('MIME-Version'):
 249             self.add_header('MIME-Version', '1.0')
 250         if not self.has_key('Content-Type'):
 251             self.add_header('Content-Type', 'text/plain',
 252                             charset=charset.get_output_charset())
 253         else:
 254             self.set_param('charset', charset.get_output_charset())
 255         if str(charset) != charset.get_output_charset():
 256             self._payload = charset.body_encode(self._payload)
 257         if not self.has_key('Content-Transfer-Encoding'):
 258             cte = charset.get_body_encoding()
 259             try:
 260                 cte(self)
 261             except TypeError:
 262                 self._payload = charset.body_encode(self._payload)
 263                 self.add_header('Content-Transfer-Encoding', cte)
 264
 265     def get_charset(self):
 266         """Return the Charset instance associated with the message's payload.
 267         """
 268         return self._charset
 269
 270     #
 271     # MAPPING INTERFACE (partial)
 272     #
 273     def __len__(self):
 274         """Return the total number of headers, including duplicates."""
 275         return len(self._headers)
 276
 277     def __getitem__(self, name):
 278         """Get a header value.
 279
 280         Return None if the header is missing instead of raising an exception.
 281
 282         Note that if the header appeared multiple times, exactly which
 283         occurrance gets returned is undefined.  Use get_all() to get all
 284         the values matching a header field name.
 285         """
 286         return self.get(name)
 287
 288     def __setitem__(self, name, val):
 289         """Set the value of a header.
 290
 291         Note: this does not overwrite an existing header with the same field
 292         name.  Use __delitem__() first to delete any existing headers.
 293         """
 294         self._headers.append((name, val))
 295
 296     def __delitem__(self, name):
 297         """Delete all occurrences of a header, if present.
 298
 299         Does not raise an exception if the header is missing.
 300         """
 301         name = name.lower()
 302         newheaders = []
 303         for k, v in self._headers:
 304             if k.lower() != name:
 305                 newheaders.append((k, v))
 306         self._headers = newheaders
 307
 308     def __contains__(self, name):
 309         return name.lower() in [k.lower() for k, v in self._headers]
 310
 311     def has_key(self, name):
 312         """Return true if the message contains the header."""
 313         missing = object()
 314         return self.get(name, missing) is not missing
 315
 316     def keys(self):
 317         """Return a list of all the message's header field names.
 318
 319         These will be sorted in the order they appeared in the original
 320         message, or were added to the message, and may contain duplicates.
 321         Any fields deleted and re-inserted are always appended to the header
 322         list.
 323         """
 324         return [k for k, v in self._headers]
 325
 326     def values(self):
 327         """Return a list of all the message's header values.
 328
 329         These will be sorted in the order they appeared in the original
 330         message, or were added to the message, and may contain duplicates.
 331         Any fields deleted and re-inserted are always appended to the header
 332         list.
 333         """
 334         return [v for k, v in self._headers]
 335
 336     def items(self):
 337         """Get all the message's header fields and values.
 338
 339         These will be sorted in the order they appeared in the original
 340         message, or were added to the message, and may contain duplicates.
 341         Any fields deleted and re-inserted are always appended to the header
 342         list.
 343         """
 344         return self._headers[:]
 345
 346     def get(self, name, failobj=None):
 347         """Get a header value.
 348
 349         Like __getitem__() but return failobj instead of None when the field
 350         is missing.
 351         """
 352         name = name.lower()
 353         for k, v in self._headers:
 354             if k.lower() == name:
 355                 return v
 356         return failobj
 357
 358     #
 359     # Additional useful stuff
 360     #
 361
 362     def get_all(self, name, failobj=None):
 363         """Return a list of all the values for the named field.
 364
 365         These will be sorted in the order they appeared in the original
 366         message, and may contain duplicates.  Any fields deleted and
 367         re-inserted are always appended to the header list.
 368
 369         If no such fields exist, failobj is returned (defaults to None).
 370         """
 371         values = []
 372         name = name.lower()
 373         for k, v in self._headers:
 374             if k.lower() == name:
 375                 values.append(v)
 376         if not values:
 377             return failobj
 378         return values
 379
 380     def add_header(self, _name, _value, **_params):
 381         """Extended header setting.
 382
 383         name is the header field to add.  keyword arguments can be used to set
 384         additional parameters for the header field, with underscores converted
 385         to dashes.  Normally the parameter will be added as key="value" unless
 386         value is None, in which case only the key will be added.
 387
 388         Example:
 389
 390         msg.add_header('content-disposition', 'attachment', filename='bud.gif')
 391         """
 392         parts = []
 393         for k, v in _params.items():
 394             if v is None:
 395                 parts.append(k.replace('_', '-'))
 396             else:
 397                 parts.append(_formatparam(k.replace('_', '-'), v))
 398         if _value is not None:
 399             parts.insert(0, _value)
 400         self._headers.append((_name, SEMISPACE.join(parts)))
 401
 402     def replace_header(self, _name, _value):
 403         """Replace a header.
 404
 405         Replace the first matching header found in the message, retaining
 406         header order and case.  If no matching header was found, a KeyError is
 407         raised.
 408         """
 409         _name = _name.lower()
 410         for i, (k, v) in zip(range(len(self._headers)), self._headers):
 411             if k.lower() == _name:
 412                 self._headers[i] = (k, _value)
 413                 break
 414         else:
 415             raise KeyError(_name)
 416
 417     #
 418     # Use these three methods instead of the three above.
 419     #
 420
 421     def get_content_type(self):
 422         """Return the message's content type.
 423
 424         The returned string is coerced to lower case of the form
 425         `maintype/subtype'.  If there was no Content-Type header in the
 426         message, the default type as given by get_default_type() will be
 427         returned.  Since according to RFC 2045, messages always have a default
 428         type this will always return a value.
 429
 430         RFC 2045 defines a message's default type to be text/plain unless it
 431         appears inside a multipart/digest container, in which case it would be
 432         message/rfc822.
 433         """
 434         missing = object()
 435         value = self.get('content-type', missing)
 436         if value is missing:
 437             # This should have no parameters
 438             return self.get_default_type()
 439         ctype = paramre.split(value)[0].lower().strip()
 440         # RFC 2045, section 5.2 says if its invalid, use text/plain
 441         if ctype.count('/') != 1:
 442             return 'text/plain'
 443         return ctype
 444
 445     def get_content_maintype(self):
 446         """Return the message's main content type.
 447
 448         This is the `maintype' part of the string returned by
 449         get_content_type().
 450         """
 451         ctype = self.get_content_type()
 452         return ctype.split('/')[0]
 453
 454     def get_content_subtype(self):
 455         """Returns the message's sub-content type.
 456
 457         This is the `subtype' part of the string returned by
 458         get_content_type().
 459         """
 460         ctype = self.get_content_type()
 461         return ctype.split('/')[1]
 462
 463     def get_default_type(self):
 464         """Return the `default' content type.
 465
 466         Most messages have a default content type of text/plain, except for
 467         messages that are subparts of multipart/digest containers.  Such
 468         subparts have a default content type of message/rfc822.
 469         """
 470         return self._default_type
 471
 472     def set_default_type(self, ctype):
 473         """Set the `default' content type.
 474
 475         ctype should be either "text/plain" or "message/rfc822", although this
 476         is not enforced.  The default content type is not stored in the
 477         Content-Type header.
 478         """
 479         self._default_type = ctype
 480
 481     def _get_params_preserve(self, failobj, header):
 482         # Like get_params() but preserves the quoting of values.  BAW:
 483         # should this be part of the public interface?
 484         missing = object()
 485         value = self.get(header, missing)
 486         if value is missing:
 487             return failobj
 488         params = []
 489         for p in _parseparam(';' + value):
 490             try:
 491                 name, val = p.split('=', 1)
 492                 name = name.strip()
 493                 val = val.strip()
 494             except ValueError:
 495                 # Must have been a bare attribute
 496                 name = p.strip()
 497                 val = ''
 498             params.append((name, val))
 499         params = utils.decode_params(params)
 500         return params
 501
 502     def get_params(self, failobj=None, header='content-type', unquote=True):
 503         """Return the message's Content-Type parameters, as a list.
 504
 505         The elements of the returned list are 2-tuples of key/value pairs, as
 506         split on the `=' sign.  The left hand side of the `=' is the key,
 507         while the right hand side is the value.  If there is no `=' sign in
 508         the parameter the value is the empty string.  The value is as
 509         described in the get_param() method.
 510
 511         Optional failobj is the object to return if there is no Content-Type
 512         header.  Optional header is the header to search instead of
 513         Content-Type.  If unquote is True, the value is unquoted.
 514         """
 515         missing = object()
 516         params = self._get_params_preserve(missing, header)
 517         if params is missing:
 518             return failobj
 519         if unquote:
 520             return [(k, _unquotevalue(v)) for k, v in params]
 521         else:
 522             return params
 523
 524     def get_param(self, param, failobj=None, header='content-type',
 525                   unquote=True):
 526         """Return the parameter value if found in the Content-Type header.
 527
 528         Optional failobj is the object to return if there is no Content-Type
 529         header, or the Content-Type header has no such parameter.  Optional
 530         header is the header to search instead of Content-Type.
 531
 532         Parameter keys are always compared case insensitively.  The return
 533         value can either be a string, or a 3-tuple if the parameter was RFC
 534         2231 encoded.  When it's a 3-tuple, the elements of the value are of
 535         the form (CHARSET, LANGUAGE, VALUE).  Note that both CHARSET and
 536         LANGUAGE can be None, in which case you should consider VALUE to be
 537         encoded in the us-ascii charset.  You can usually ignore LANGUAGE.
 538
 539         Your application should be prepared to deal with 3-tuple return
 540         values, and can convert the parameter to a Unicode string like so:
 541
 542             param = msg.get_param('foo')
 543             if isinstance(param, tuple):
 544                 param = unicode(param[2], param[0] or 'us-ascii')
 545
 546         In any case, the parameter value (either the returned string, or the
 547         VALUE item in the 3-tuple) is always unquoted, unless unquote is set
 548         to False.
 549         """
 550         if not self.has_key(header):
 551             return failobj
 552         for k, v in self._get_params_preserve(failobj, header):
 553             if k.lower() == param.lower():
 554                 if unquote:
 555                     return _unquotevalue(v)
 556                 else:
 557                     return v
 558         return failobj
 559
 560     def set_param(self, param, value, header='Content-Type', requote=True,
 561                   charset=None, language=''):
 562         """Set a parameter in the Content-Type header.
 563
 564         If the parameter already exists in the header, its value will be
 565         replaced with the new value.
 566
 567         If header is Content-Type and has not yet been defined for this
 568         message, it will be set to "text/plain" and the new parameter and
 569         value will be appended as per RFC 2045.
 570
 571         An alternate header can specified in the header argument, and all
 572         parameters will be quoted as necessary unless requote is False.
 573
 574         If charset is specified, the parameter will be encoded according to RFC
 575         2231.  Optional language specifies the RFC 2231 language, defaulting
 576         to the empty string.  Both charset and language should be strings.
 577         """
 578         if not isinstance(value, tuple) and charset:
 579             value = (charset, language, value)
 580
 581         if not self.has_key(header) and header.lower() == 'content-type':
 582             ctype = 'text/plain'
 583         else:
 584             ctype = self.get(header)
 585         if not self.get_param(param, header=header):
 586             if not ctype:
 587                 ctype = _formatparam(param, value, requote)
 588             else:
 589                 ctype = SEMISPACE.join(
 590                     [ctype, _formatparam(param, value, requote)])
 591         else:
 592             ctype = ''
 593             for old_param, old_value in self.get_params(header=header,
 594                                                         unquote=requote):
 595                 append_param = ''
 596                 if old_param.lower() == param.lower():
 597                     append_param = _formatparam(param, value, requote)
 598                 else:
 599                     append_param = _formatparam(old_param, old_value, requote)
 600                 if not ctype:
 601                     ctype = append_param
 602                 else:
 603                     ctype = SEMISPACE.join([ctype, append_param])
 604         if ctype != self.get(header):
 605             del self[header]
 606             self[header] = ctype
 607
 608     def del_param(self, param, header='content-type', requote=True):
 609         """Remove the given parameter completely from the Content-Type header.
 610
 611         The header will be re-written in place without the parameter or its
 612         value. All values will be quoted as necessary unless requote is
 613         False.  Optional header specifies an alternative to the Content-Type
 614         header.
 615         """
 616         if not self.has_key(header):
 617             return
 618         new_ctype = ''
 619         for p, v in self.get_params(header=header, unquote=requote):
 620             if p.lower() != param.lower():
 621                 if not new_ctype:
 622                     new_ctype = _formatparam(p, v, requote)
 623                 else:
 624                     new_ctype = SEMISPACE.join([new_ctype,
 625                                                 _formatparam(p, v, requote)])
 626         if new_ctype != self.get(header):
 627             del self[header]
 628             self[header] = new_ctype
 629
 630     def set_type(self, type, header='Content-Type', requote=True):
 631         """Set the main type and subtype for the Content-Type header.
 632
 633         type must be a string in the form "maintype/subtype", otherwise a
 634         ValueError is raised.
 635
 636         This method replaces the Content-Type header, keeping all the
 637         parameters in place.  If requote is False, this leaves the existing
 638         header's quoting as is.  Otherwise, the parameters will be quoted (the
 639         default).
 640
 641         An alternative header can be specified in the header argument.  When
 642         the Content-Type header is set, we'll always also add a MIME-Version
 643         header.
 644         """
 645         # BAW: should we be strict?
 646         if not type.count('/') == 1:
 647             raise ValueError
 648         # Set the Content-Type, you get a MIME-Version
 649         if header.lower() == 'content-type':
 650             del self['mime-version']
 651             self['MIME-Version'] = '1.0'
 652         if not self.has_key(header):
 653             self[header] = type
 654             return
 655         params = self.get_params(header=header, unquote=requote)
 656         del self[header]
 657         self[header] = type
 658         # Skip the first param; it's the old type.
 659         for p, v in params[1:]:
 660             self.set_param(p, v, header, requote)
 661
 662     def get_filename(self, failobj=None):
 663         """Return the filename associated with the payload if present.
 664
 665         The filename is extracted from the Content-Disposition header's
 666         `filename' parameter, and it is unquoted.  If that header is missing
 667         the `filename' parameter, this method falls back to looking for the
 668         `name' parameter.
 669         """
 670         missing = object()
 671         filename = self.get_param('filename', missing, 'content-disposition')
 672         if filename is missing:
 673             filename = self.get_param('name', missing, 'content-disposition')
 674         if filename is missing:
 675             return failobj
 676         return utils.collapse_rfc2231_value(filename).strip()
 677
 678     def get_boundary(self, failobj=None):
 679         """Return the boundary associated with the payload if present.
 680
 681         The boundary is extracted from the Content-Type header's `boundary'
 682         parameter, and it is unquoted.
 683         """
 684         missing = object()
 685         boundary = self.get_param('boundary', missing)
 686         if boundary is missing:
 687             return failobj
 688         # RFC 2046 says that boundaries may begin but not end in w/s
 689         return utils.collapse_rfc2231_value(boundary).rstrip()
 690
 691     def set_boundary(self, boundary):
 692         """Set the boundary parameter in Content-Type to 'boundary'.
 693
 694         This is subtly different than deleting the Content-Type header and
 695         adding a new one with a new boundary parameter via add_header().  The
 696         main difference is that using the set_boundary() method preserves the
 697         order of the Content-Type header in the original message.
 698
 699         HeaderParseError is raised if the message has no Content-Type header.
 700         """
 701         missing = object()
 702         params = self._get_params_preserve(missing, 'content-type')
 703         if params is missing:
 704             # There was no Content-Type header, and we don't know what type
 705             # to set it to, so raise an exception.
 706             raise errors.HeaderParseError('No Content-Type header found')
 707         newparams = []
 708         foundp = False
 709         for pk, pv in params:
 710             if pk.lower() == 'boundary':
 711                 newparams.append(('boundary', '"%s"' % boundary))
 712                 foundp = True
 713             else:
 714                 newparams.append((pk, pv))
 715         if not foundp:
 716             # The original Content-Type header had no boundary attribute.
 717             # Tack one on the end.  BAW: should we raise an exception
 718             # instead???
 719             newparams.append(('boundary', '"%s"' % boundary))
 720         # Replace the existing Content-Type header with the new value
 721         newheaders = []
 722         for h, v in self._headers:
 723             if h.lower() == 'content-type':
 724                 parts = []
 725                 for k, v in newparams:
 726                     if v == '':
 727                         parts.append(k)
 728                     else:
 729                         parts.append('%s=%s' % (k, v))
 730                 newheaders.append((h, SEMISPACE.join(parts)))
 731
 732             else:
 733                 newheaders.append((h, v))
 734         self._headers = newheaders
 735
 736     def get_content_charset(self, failobj=None):
 737         """Return the charset parameter of the Content-Type header.
 738
 739         The returned string is always coerced to lower case.  If there is no
 740         Content-Type header, or if that header has no charset parameter,
 741         failobj is returned.
 742         """
 743         missing = object()
 744         charset = self.get_param('charset', missing)
 745         if charset is missing:
 746             return failobj
 747         if isinstance(charset, tuple):
 748             # RFC 2231 encoded, so decode it, and it better end up as ascii.
 749             pcharset = charset[0] or 'us-ascii'
 750             try:
 751                 # LookupError will be raised if the charset isn't known to
 752                 # Python.  UnicodeError will be raised if the encoded text
 753                 # contains a character not in the charset.
 754                 charset = unicode(charset[2], pcharset).encode('us-ascii')
 755             except (LookupError, UnicodeError):
 756                 charset = charset[2]
 757         # charset character must be in us-ascii range
 758         try:
 759             if isinstance(charset, str):
 760                 charset = unicode(charset, 'us-ascii')
 761             charset = charset.encode('us-ascii')
 762         except UnicodeError:
 763             return failobj
 764         # RFC 2046, $4.1.2 says charsets are not case sensitive
 765         return charset.lower()
 766
 767     def get_charsets(self, failobj=None):
 768         """Return a list containing the charset(s) used in this message.
 769
 770         The returned list of items describes the Content-Type headers'
 771         charset parameter for this message and all the subparts in its
 772         payload.
 773
 774         Each item will either be a string (the value of the charset parameter
 775         in the Content-Type header of that part) or the value of the
 776         'failobj' parameter (defaults to None), if the part does not have a
 777         main MIME type of "text", or the charset is not defined.
 778
 779         The list will contain one string for each part of the message, plus
 780         one for the container message (i.e. self), so that a non-multipart
 781         message will still return a list of length 1.
 782         """
 783         return [part.get_content_charset(failobj) for part in self.walk()]
 784
 785     # I.e. def walk(self): ...
 786     from email.Iterators import walk