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 

    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 

    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