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