Debian Codegraph @

Lib/email/message.py

raw
1 # Copyright (C) 2001 Python Software Foundation
2 # Author: Barry Warsaw
3 # Contact: [email protected]
4
5 """Basic message object for the email package object model."""
6
7 __all__ = ['Message', 'EmailMessage']
8
9 import binascii
10 import re
11 import quopri
12 from io import BytesIO, StringIO
13
14 # Intrapackage imports
15 from email import utils
16 from email import errors
17 from email._policybase import compat32
18 from email import charset as _charset
19 from email._encoded_words import decode_b
20 Charset = _charset.Charset
21
22 SEMISPACE = '; '
23
24 # Regular expression that matches 'special' characters in parameters, the
25 # existence of which force quoting of the parameter value.
26 tspecials = re.compile(r'[ \(\)<>@,;:\\"/\[\]\?=]')
27
28
29 def _splitparam(param):
30 # Split header parameters. BAW: this may be too simple. It isn't
31 # strictly RFC 2045 (section 5.1) compliant, but it catches most headers
32 # found in the wild. We may eventually need a full fledged parser.
33 # RDM: we might have a Header here; for now just stringify it.
34 a, sep, b = str(param).partition(';')
35 if not sep:
36 return a.strip(), None
37 return a.strip(), b.strip()
38
39 def _formatparam(param, value=None, quote=True):
40 """Convenience function to format and return a key=value pair.
41
42 This will quote the value if needed or if quote is true. If value is a
43 three tuple (charset, language, value), it will be encoded according
44 to RFC2231 rules. If it contains non-ascii characters it will likewise
45 be encoded according to RFC2231 rules, using the utf-8 charset and
46 a null language.
47 """
48 if value is not None and len(value) > 0:
49 # A tuple is used for RFC 2231 encoded parameter values where items
50 # are (charset, language, value). charset is a string, not a Charset
51 # instance. RFC 2231 encoded values are never quoted, per RFC.
52 if isinstance(value, tuple):
53 # Encode as per RFC 2231
54 param += '*'
55 value = utils.encode_rfc2231(value[2], value[0], value[1])
56 return '%s=%s' % (param, value)
57 else:
58 try:
59 value.encode('ascii')
60 except UnicodeEncodeError:
61 param += '*'
62 value = utils.encode_rfc2231(value, 'utf-8', '')
63 return '%s=%s' % (param, value)
64 # BAW: Please check this. I think that if quote is set it should
65 # force quoting even if not necessary.
66 if quote or tspecials.search(value):
67 return '%s="%s"' % (param, utils.quote(value))
68 else:
69 return '%s=%s' % (param, value)
70 else:
71 return param
72
73 def _parseparam(s):
74 # RDM This might be a Header, so for now stringify it.
75 s = ';' + str(s)
76 plist = []
77 start = 0
78 while s.find(';', start) == start:
79 start += 1
80 end = s.find(';', start)
81 ind, diff = start, 0
82 while end > 0:
83 diff += s.count('"', ind, end) - s.count('\\"', ind, end)
84 if diff % 2 == 0:
85 break
86 end, ind = ind, s.find(';', end + 1)
87 if end < 0:
88 end = len(s)
89 i = s.find('=', start, end)
90 if i == -1:
91 f = s[start:end]
92 else:
93 f = s[start:i].rstrip().lower() + '=' + s[i+1:end].lstrip()
94 plist.append(f.strip())
95 start = end
96 return plist
97
98
99 def _unquotevalue(value):
100 # This is different than utils.collapse_rfc2231_value() because it doesn't
101 # try to convert the value to a unicode. Message.get_param() and
102 # Message.get_params() are both currently defined to return the tuple in
103 # the face of RFC 2231 parameters.
104 if isinstance(value, tuple):
105 return value[0], value[1], utils.unquote(value[2])
106 else:
107 return utils.unquote(value)
108
109
110 def _decode_uu(encoded):
111 """Decode uuencoded data."""
112 decoded_lines = []
113 encoded_lines_iter = iter(encoded.splitlines())
114 for line in encoded_lines_iter:
115 if line.startswith(b"begin "):
116 mode, _, path = line.removeprefix(b"begin ").partition(b" ")
117 try:
118 int(mode, base=8)
119 except ValueError:
120 continue
121 else:
122 break
123 else:
124 raise ValueError("`begin` line not found")
125 for line in encoded_lines_iter:
126 if not line:
127 raise ValueError("Truncated input")
128 elif line.strip(b' \t\r\n\f') == b'end':
129 break
130 try:
131 decoded_line = binascii.a2b_uu(line)
132 except binascii.Error:
133 # Workaround for broken uuencoders by /Fredrik Lundh
134 nbytes = (((line[0]-32) & 63) * 4 + 5) // 3
135 decoded_line = binascii.a2b_uu(line[:nbytes])
136 decoded_lines.append(decoded_line)
137
138 return b''.join(decoded_lines)
139
140
141 class Message:
142 """Basic message object.
143
144 A message object is defined as something that has a bunch of RFC 5322
145 headers and a payload. It may optionally have an envelope header
146 (a.k.a. Unix-From or From_ header). If the message is a container (i.e. a
147 multipart or a message/rfc822), then the payload is a list of Message
148 objects, otherwise it is a string.
149
150 Message objects implement part of the 'mapping' interface, which assumes
151 there is exactly one occurrence of the header per message. Some headers
152 do in fact appear multiple times (e.g. Received) and for those headers,
153 you must use the explicit API to set or get all the headers. Not all of
154 the mapping methods are implemented.
155 """
156 def __init__(self, policy=compat32):
157 self.policy = policy
158 self._headers = []
159 self._unixfrom = None
160 self._payload = None
161 self._charset = None
162 # Defaults for multipart messages
163 self.preamble = self.epilogue = None
164 self.defects = []
165 # Default content type
166 self._default_type = 'text/plain'
167
168 def __str__(self):
169 """Return the entire formatted message as a string.
170 """
171 return self.as_string()
172
173 def as_string(self, unixfrom=False, maxheaderlen=0, policy=None):
174 """Return the entire formatted message as a string.
175
176 Optional 'unixfrom', when true, means include the Unix From_ envelope
177 header. For backward compatibility reasons, if maxheaderlen is
178 not specified it defaults to 0, so you must override it explicitly
179 if you want a different maxheaderlen. 'policy' is passed to the
180 Generator instance used to serialize the message; if it is not
181 specified the policy associated with the message instance is used.
182
183 If the message object contains binary data that is not encoded
184 according to RFC standards, the non-compliant data will be replaced by
185 unicode "unknown character" code points.
186 """
187 from email.generator import Generator
188 policy = self.policy if policy is None else policy
189 fp = StringIO()
190 g = Generator(fp,
191 mangle_from_=False,
192 maxheaderlen=maxheaderlen,
193 policy=policy)
194 g.flatten(self, unixfrom=unixfrom)
195 return fp.getvalue()
196
197 def __bytes__(self):
198 """Return the entire formatted message as a bytes object.
199 """
200 return self.as_bytes()
201
202 def as_bytes(self, unixfrom=False, policy=None):
203 """Return the entire formatted message as a bytes object.
204
205 Optional 'unixfrom', when true, means include the Unix From_ envelope
206 header. 'policy' is passed to the BytesGenerator instance used to
207 serialize the message; if not specified the policy associated with
208 the message instance is used.
209 """
210 from email.generator import BytesGenerator
211 policy = self.policy if policy is None else policy
212 fp = BytesIO()
213 g = BytesGenerator(fp, mangle_from_=False, policy=policy)
214 g.flatten(self, unixfrom=unixfrom)
215 return fp.getvalue()
216
217 def is_multipart(self):
218 """Return True if the message consists of multiple parts."""
219 return isinstance(self._payload, list)
220
221 #
222 # Unix From_ line
223 #
224 def set_unixfrom(self, unixfrom):
225 self._unixfrom = unixfrom
226
227 def get_unixfrom(self):
228 return self._unixfrom
229
230 #
231 # Payload manipulation.
232 #
233 def attach(self, payload):
234 """Add the given payload to the current payload.
235
236 The current payload will always be a list of objects after this method
237 is called. If you want to set the payload to a scalar object, use
238 set_payload() instead.
239 """
240 if self._payload is None:
241 self._payload = [payload]
242 else:
243 try:
244 self._payload.append(payload)
245 except AttributeError:
246 raise TypeError("Attach is not valid on a message with a"
247 " non-multipart payload")
248
249 def get_payload(self, i=None, decode=False):
250 """Return a reference to the payload.
251
252 The payload will either be a list object or a string. If you mutate
253 the list object, you modify the message's payload in place. Optional
254 i returns that index into the payload.
255
256 Optional decode is a flag indicating whether the payload should be
257 decoded or not, according to the Content-Transfer-Encoding header
258 (default is False).
259
260 When True and the message is not a multipart, the payload will be
261 decoded if this header's value is `quoted-printable' or `base64'. If
262 some other encoding is used, or the header is missing, or if the
263 payload has bogus data (i.e. bogus base64 or uuencoded data), the
264 payload is returned as-is.
265
266 If the message is a multipart and the decode flag is True, then None
267 is returned.
268 """
269 # Here is the logic table for this code, based on the email5.0.0 code:
270 # i decode is_multipart result
271 # ------ ------ ------------ ------------------------------
272 # None True True None
273 # i True True None
274 # None False True _payload (a list)
275 # i False True _payload element i (a Message)
276 # i False False error (not a list)
277 # i True False error (not a list)
278 # None False False _payload
279 # None True False _payload decoded (bytes)
280 # Note that Barry planned to factor out the 'decode' case, but that
281 # isn't so easy now that we handle the 8 bit data, which needs to be
282 # converted in both the decode and non-decode path.
283 if self.is_multipart():
284 if decode:
285 return None
286 if i is None:
287 return self._payload
288 else:
289 return self._payload[i]
290 # For backward compatibility, Use isinstance and this error message
291 # instead of the more logical is_multipart test.
292 if i is not None and not isinstance(self._payload, list):
293 raise TypeError('Expected list, got %s' % type(self._payload))
294 payload = self._payload
295 cte = self.get('content-transfer-encoding', '')
296 if hasattr(cte, 'cte'):
297 cte = cte.cte
298 else:
299 # cte might be a Header, so for now stringify it.
300 cte = str(cte).strip().lower()
301 # payload may be bytes here.
302 if not decode:
303 if isinstance(payload, str) and utils._has_surrogates(payload):
304 try:
305 bpayload = payload.encode('ascii', 'surrogateescape')
306 try:
307 payload = bpayload.decode(self.get_content_charset('ascii'), 'replace')
308 except LookupError:
309 payload = bpayload.decode('ascii', 'replace')
310 except UnicodeEncodeError:
311 pass
312 return payload
313 if isinstance(payload, str):
314 try:
315 bpayload = payload.encode('ascii', 'surrogateescape')
316 except UnicodeEncodeError:
317 # This won't happen for RFC compliant messages (messages
318 # containing only ASCII code points in the unicode input).
319 # If it does happen, turn the string into bytes in a way
320 # guaranteed not to fail.
321 bpayload = payload.encode('raw-unicode-escape')
322 else:
323 bpayload = payload
324 if cte == 'quoted-printable':
325 return quopri.decodestring(bpayload)
326 elif cte == 'base64':
327 # XXX: this is a bit of a hack; decode_b should probably be factored
328 # out somewhere, but I haven't figured out where yet.
329 value, defects = decode_b(b''.join(bpayload.splitlines()))
330 for defect in defects:
331 self.policy.handle_defect(self, defect)
332 return value
333 elif cte in ('x-uuencode', 'uuencode', 'uue', 'x-uue'):
334 try:
335 return _decode_uu(bpayload)
336 except ValueError:
337 # Some decoding problem.
338 return bpayload
339 if isinstance(payload, str):
340 return bpayload
341 return payload
342
343 def set_payload(self, payload, charset=None):
344 """Set the payload to the given value.
345
346 Optional charset sets the message's default character set. See
347 set_charset() for details.
348 """
349 if hasattr(payload, 'encode'):
350 if charset is None:
351 self._payload = payload
352 return
353 if not isinstance(charset, Charset):
354 charset = Charset(charset)
355 payload = payload.encode(charset.output_charset, 'surrogateescape')
356 if hasattr(payload, 'decode'):
357 self._payload = payload.decode('ascii', 'surrogateescape')
358 else:
359 self._payload = payload
360 if charset is not None:
361 self.set_charset(charset)
362
363 def set_charset(self, charset):
364 """Set the charset of the payload to a given character set.
365
366 charset can be a Charset instance, a string naming a character set, or
367 None. If it is a string it will be converted to a Charset instance.
368 If charset is None, the charset parameter will be removed from the
369 Content-Type field. Anything else will generate a TypeError.
370
371 The message will be assumed to be of type text/* encoded with
372 charset.input_charset. It will be converted to charset.output_charset
373 and encoded properly, if needed, when generating the plain text
374 representation of the message. MIME headers (MIME-Version,
375 Content-Type, Content-Transfer-Encoding) will be added as needed.
376 """
377 if charset is None:
378 self.del_param('charset')
379 self._charset = None
380 return
381 if not isinstance(charset, Charset):
382 charset = Charset(charset)
383 self._charset = charset
384 if 'MIME-Version' not in self:
385 self.add_header('MIME-Version', '1.0')
386 if 'Content-Type' not in self:
387 self.add_header('Content-Type', 'text/plain',
388 charset=charset.get_output_charset())
389 else:
390 self.set_param('charset', charset.get_output_charset())
391 if charset != charset.get_output_charset():
392 self._payload = charset.body_encode(self._payload)
393 if 'Content-Transfer-Encoding' not in self:
394 cte = charset.get_body_encoding()
395 try:
396 cte(self)
397 except TypeError:
398 # This 'if' is for backward compatibility, it allows unicode
399 # through even though that won't work correctly if the
400 # message is serialized.
401 payload = self._payload
402 if payload:
403 try:
404 payload = payload.encode('ascii', 'surrogateescape')
405 except UnicodeError:
406 payload = payload.encode(charset.output_charset)
407 self._payload = charset.body_encode(payload)
408 self.add_header('Content-Transfer-Encoding', cte)
409
410 def get_charset(self):
411 """Return the Charset instance associated with the message's payload.
412 """
413 return self._charset
414
415 #
416 # MAPPING INTERFACE (partial)
417 #
418 def __len__(self):
419 """Return the total number of headers, including duplicates."""
420 return len(self._headers)
421
422 def __getitem__(self, name):
423 """Get a header value.
424
425 Return None if the header is missing instead of raising an exception.
426
427 Note that if the header appeared multiple times, exactly which
428 occurrence gets returned is undefined. Use get_all() to get all
429 the values matching a header field name.
430 """
431 return self.get(name)
432
433 def __setitem__(self, name, val):
434 """Set the value of a header.
435
436 Note: this does not overwrite an existing header with the same field
437 name. Use __delitem__() first to delete any existing headers.
438 """
439 max_count = self.policy.header_max_count(name)
440 if max_count:
441 lname = name.lower()
442 found = 0
443 for k, v in self._headers:
444 if k.lower() == lname:
445 found += 1
446 if found >= max_count:
447 raise ValueError("There may be at most {} {} headers "
448 "in a message".format(max_count, name))
449 self._headers.append(self.policy.header_store_parse(name, val))
450
451 def __delitem__(self, name):
452 """Delete all occurrences of a header, if present.
453
454 Does not raise an exception if the header is missing.
455 """
456 name = name.lower()
457 newheaders = []
458 for k, v in self._headers:
459 if k.lower() != name:
460 newheaders.append((k, v))
461 self._headers = newheaders
462
463 def __contains__(self, name):
464 name_lower = name.lower()
465 for k, v in self._headers:
466 if name_lower == k.lower():
467 return True
468 return False
469
470 def __iter__(self):
471 for field, value in self._headers:
472 yield field
473
474 def keys(self):
475 """Return a list of all the message's header field names.
476
477 These will be sorted in the order they appeared in the original
478 message, or were added to the message, and may contain duplicates.
479 Any fields deleted and re-inserted are always appended to the header
480 list.
481 """
482 return [k for k, v in self._headers]
483
484 def values(self):
485 """Return a list of all the message's header values.
486
487 These will be sorted in the order they appeared in the original
488 message, or were added to the message, and may contain duplicates.
489 Any fields deleted and re-inserted are always appended to the header
490 list.
491 """
492 return [self.policy.header_fetch_parse(k, v)
493 for k, v in self._headers]
494
495 def items(self):
496 """Get all the message's header fields and values.
497
498 These will be sorted in the order they appeared in the original
499 message, or were added to the message, and may contain duplicates.
500 Any fields deleted and re-inserted are always appended to the header
501 list.
502 """
503 return [(k, self.policy.header_fetch_parse(k, v))
504 for k, v in self._headers]
505
506 def get(self, name, failobj=None):
507 """Get a header value.
508
509 Like __getitem__() but return failobj instead of None when the field
510 is missing.
511 """
512 name = name.lower()
513 for k, v in self._headers:
514 if k.lower() == name:
515 return self.policy.header_fetch_parse(k, v)
516 return failobj
517
518 #
519 # "Internal" methods (public API, but only intended for use by a parser
520 # or generator, not normal application code.
521 #
522
523 def set_raw(self, name, value):
524 """Store name and value in the model without modification.
525
526 This is an "internal" API, intended only for use by a parser.
527 """
528 self._headers.append((name, value))
529
530 def raw_items(self):
531 """Return the (name, value) header pairs without modification.
532
533 This is an "internal" API, intended only for use by a generator.
534 """
535 return iter(self._headers.copy())
536
537 #
538 # Additional useful stuff
539 #
540
541 def get_all(self, name, failobj=None):
542 """Return a list of all the values for the named field.
543
544 These will be sorted in the order they appeared in the original
545 message, and may contain duplicates. Any fields deleted and
546 re-inserted are always appended to the header list.
547
548 If no such fields exist, failobj is returned (defaults to None).
549 """
550 values = []
551 name = name.lower()
552 for k, v in self._headers:
553 if k.lower() == name:
554 values.append(self.policy.header_fetch_parse(k, v))
555 if not values:
556 return failobj
557 return values
558
559 def add_header(self, _name, _value, **_params):
560 """Extended header setting.
561
562 name is the header field to add. keyword arguments can be used to set
563 additional parameters for the header field, with underscores converted
564 to dashes. Normally the parameter will be added as key="value" unless
565 value is None, in which case only the key will be added. If a
566 parameter value contains non-ASCII characters it can be specified as a
567 three-tuple of (charset, language, value), in which case it will be
568 encoded according to RFC2231 rules. Otherwise it will be encoded using
569 the utf-8 charset and a language of ''.
570
571 Examples:
572
573 msg.add_header('content-disposition', 'attachment', filename='bud.gif')
574 msg.add_header('content-disposition', 'attachment',
575 filename=('utf-8', '', 'Fußballer.ppt'))
576 msg.add_header('content-disposition', 'attachment',
577 filename='Fußballer.ppt'))
578 """
579 parts = []
580 for k, v in _params.items():
581 if v is None:
582 parts.append(k.replace('_', '-'))
583 else:
584 parts.append(_formatparam(k.replace('_', '-'), v))
585 if _value is not None:
586 parts.insert(0, _value)
587 self[_name] = SEMISPACE.join(parts)
588
589 def replace_header(self, _name, _value):
590 """Replace a header.
591
592 Replace the first matching header found in the message, retaining
593 header order and case. If no matching header was found, a KeyError is
594 raised.
595 """
596 _name = _name.lower()
597 for i, (k, v) in zip(range(len(self._headers)), self._headers):
598 if k.lower() == _name:
599 self._headers[i] = self.policy.header_store_parse(k, _value)
600 break
601 else:
602 raise KeyError(_name)
603
604 #
605 # Use these three methods instead of the three above.
606 #
607
608 def get_content_type(self):
609 """Return the message's content type.
610
611 The returned string is coerced to lower case of the form
612 'maintype/subtype'. If there was no Content-Type header in the
613 message, the default type as given by get_default_type() will be
614 returned. Since according to RFC 2045, messages always have a default
615 type this will always return a value.
616
617 RFC 2045 defines a message's default type to be text/plain unless it
618 appears inside a multipart/digest container, in which case it would be
619 message/rfc822.
620 """
621 missing = object()
622 value = self.get('content-type', missing)
623 if value is missing:
624 # This should have no parameters
625 return self.get_default_type()
626 ctype = _splitparam(value)[0].lower()
627 # RFC 2045, section 5.2 says if its invalid, use text/plain
628 if ctype.count('/') != 1:
629 return 'text/plain'
630 return ctype
631
632 def get_content_maintype(self):
633 """Return the message's main content type.
634
635 This is the 'maintype' part of the string returned by
636 get_content_type().
637 """
638 ctype = self.get_content_type()
639 return ctype.split('/')[0]
640
641 def get_content_subtype(self):
642 """Returns the message's sub-content type.
643
644 This is the 'subtype' part of the string returned by
645 get_content_type().
646 """
647 ctype = self.get_content_type()
648 return ctype.split('/')[1]
649
650 def get_default_type(self):
651 """Return the 'default' content type.
652
653 Most messages have a default content type of text/plain, except for
654 messages that are subparts of multipart/digest containers. Such
655 subparts have a default content type of message/rfc822.
656 """
657 return self._default_type
658
659 def set_default_type(self, ctype):
660 """Set the 'default' content type.
661
662 ctype should be either "text/plain" or "message/rfc822", although this
663 is not enforced. The default content type is not stored in the
664 Content-Type header.
665 """
666 self._default_type = ctype
667
668 def _get_params_preserve(self, failobj, header):
669 # Like get_params() but preserves the quoting of values. BAW:
670 # should this be part of the public interface?
671 missing = object()
672 value = self.get(header, missing)
673 if value is missing:
674 return failobj
675 params = []
676 for p in _parseparam(value):
677 try:
678 name, val = p.split('=', 1)
679 name = name.strip()
680 val = val.strip()
681 except ValueError:
682 # Must have been a bare attribute
683 name = p.strip()
684 val = ''
685 params.append((name, val))
686 params = utils.decode_params(params)
687 return params
688
689 def get_params(self, failobj=None, header='content-type', unquote=True):
690 """Return the message's Content-Type parameters, as a list.
691
692 The elements of the returned list are 2-tuples of key/value pairs, as
693 split on the '=' sign. The left hand side of the '=' is the key,
694 while the right hand side is the value. If there is no '=' sign in
695 the parameter the value is the empty string. The value is as
696 described in the get_param() method.
697
698 Optional failobj is the object to return if there is no Content-Type
699 header. Optional header is the header to search instead of
700 Content-Type. If unquote is True, the value is unquoted.
701 """
702 missing = object()
703 params = self._get_params_preserve(missing, header)
704 if params is missing:
705 return failobj
706 if unquote:
707 return [(k, _unquotevalue(v)) for k, v in params]
708 else:
709 return params
710
711 def get_param(self, param, failobj=None, header='content-type',
712 unquote=True):
713 """Return the parameter value if found in the Content-Type header.
714
715 Optional failobj is the object to return if there is no Content-Type
716 header, or the Content-Type header has no such parameter. Optional
717 header is the header to search instead of Content-Type.
718
719 Parameter keys are always compared case insensitively. The return
720 value can either be a string, or a 3-tuple if the parameter was RFC
721 2231 encoded. When it's a 3-tuple, the elements of the value are of
722 the form (CHARSET, LANGUAGE, VALUE). Note that both CHARSET and
723 LANGUAGE can be None, in which case you should consider VALUE to be
724 encoded in the us-ascii charset. You can usually ignore LANGUAGE.
725 The parameter value (either the returned string, or the VALUE item in
726 the 3-tuple) is always unquoted, unless unquote is set to False.
727
728 If your application doesn't care whether the parameter was RFC 2231
729 encoded, it can turn the return value into a string as follows:
730
731 rawparam = msg.get_param('foo')
732 param = email.utils.collapse_rfc2231_value(rawparam)
733
734 """
735 if header not in self:
736 return failobj
737 for k, v in self._get_params_preserve(failobj, header):
738 if k.lower() == param.lower():
739 if unquote:
740 return _unquotevalue(v)
741 else:
742 return v
743 return failobj
744
745 def set_param(self, param, value, header='Content-Type', requote=True,
746 charset=None, language='', replace=False):
747 """Set a parameter in the Content-Type header.
748
749 If the parameter already exists in the header, its value will be
750 replaced with the new value.
751
752 If header is Content-Type and has not yet been defined for this
753 message, it will be set to "text/plain" and the new parameter and
754 value will be appended as per RFC 2045.
755
756 An alternate header can be specified in the header argument, and all
757 parameters will be quoted as necessary unless requote is False.
758
759 If charset is specified, the parameter will be encoded according to RFC
760 2231. Optional language specifies the RFC 2231 language, defaulting
761 to the empty string. Both charset and language should be strings.
762 """
763 if not isinstance(value, tuple) and charset:
764 value = (charset, language, value)
765
766 if header not in self and header.lower() == 'content-type':
767 ctype = 'text/plain'
768 else:
769 ctype = self.get(header)
770 if not self.get_param(param, header=header):
771 if not ctype:
772 ctype = _formatparam(param, value, requote)
773 else:
774 ctype = SEMISPACE.join(
775 [ctype, _formatparam(param, value, requote)])
776 else:
777 ctype = ''
778 for old_param, old_value in self.get_params(header=header,
779 unquote=requote):
780 append_param = ''
781 if old_param.lower() == param.lower():
782 append_param = _formatparam(param, value, requote)
783 else:
784 append_param = _formatparam(old_param, old_value, requote)
785 if not ctype:
786 ctype = append_param
787 else:
788 ctype = SEMISPACE.join([ctype, append_param])
789 if ctype != self.get(header):
790 if replace:
791 self.replace_header(header, ctype)
792 else:
793 del self[header]
794 self[header] = ctype
795
796 def del_param(self, param, header='content-type', requote=True):
797 """Remove the given parameter completely from the Content-Type header.
798
799 The header will be re-written in place without the parameter or its
800 value. All values will be quoted as necessary unless requote is
801 False. Optional header specifies an alternative to the Content-Type
802 header.
803 """
804 if header not in self:
805 return
806 new_ctype = ''
807 for p, v in self.get_params(header=header, unquote=requote):
808 if p.lower() != param.lower():
809 if not new_ctype:
810 new_ctype = _formatparam(p, v, requote)
811 else:
812 new_ctype = SEMISPACE.join([new_ctype,
813 _formatparam(p, v, requote)])
814 if new_ctype != self.get(header):
815 del self[header]
816 self[header] = new_ctype
817
818 def set_type(self, type, header='Content-Type', requote=True):
819 """Set the main type and subtype for the Content-Type header.
820
821 type must be a string in the form "maintype/subtype", otherwise a
822 ValueError is raised.
823
824 This method replaces the Content-Type header, keeping all the
825 parameters in place. If requote is False, this leaves the existing
826 header's quoting as is. Otherwise, the parameters will be quoted (the
827 default).
828
829 An alternative header can be specified in the header argument. When
830 the Content-Type header is set, we'll always also add a MIME-Version
831 header.
832 """
833 # BAW: should we be strict?
834 if not type.count('/') == 1:
835 raise ValueError
836 # Set the Content-Type, you get a MIME-Version
837 if header.lower() == 'content-type':
838 del self['mime-version']
839 self['MIME-Version'] = '1.0'
840 if header not in self:
841 self[header] = type
842 return
843 params = self.get_params(header=header, unquote=requote)
844 del self[header]
845 self[header] = type
846 # Skip the first param; it's the old type.
847 for p, v in params[1:]:
848 self.set_param(p, v, header, requote)
849
850 def get_filename(self, failobj=None):
851 """Return the filename associated with the payload if present.
852
853 The filename is extracted from the Content-Disposition header's
854 'filename' parameter, and it is unquoted. If that header is missing
855 the 'filename' parameter, this method falls back to looking for the
856 'name' parameter.
857 """
858 missing = object()
859 filename = self.get_param('filename', missing, 'content-disposition')
860 if filename is missing:
861 filename = self.get_param('name', missing, 'content-type')
862 if filename is missing:
863 return failobj
864 return utils.collapse_rfc2231_value(filename).strip()
865
866 def get_boundary(self, failobj=None):
867 """Return the boundary associated with the payload if present.
868
869 The boundary is extracted from the Content-Type header's 'boundary'
870 parameter, and it is unquoted.
871 """
872 missing = object()
873 boundary = self.get_param('boundary', missing)
874 if boundary is missing:
875 return failobj
876 # RFC 2046 says that boundaries may begin but not end in w/s
877 return utils.collapse_rfc2231_value(boundary).rstrip()
878
879 def set_boundary(self, boundary):
880 """Set the boundary parameter in Content-Type to 'boundary'.
881
882 This is subtly different than deleting the Content-Type header and
883 adding a new one with a new boundary parameter via add_header(). The
884 main difference is that using the set_boundary() method preserves the
885 order of the Content-Type header in the original message.
886
887 HeaderParseError is raised if the message has no Content-Type header.
888 """
889 missing = object()
890 params = self._get_params_preserve(missing, 'content-type')
891 if params is missing:
892 # There was no Content-Type header, and we don't know what type
893 # to set it to, so raise an exception.
894 raise errors.HeaderParseError('No Content-Type header found')
895 newparams = []
896 foundp = False
897 for pk, pv in params:
898 if pk.lower() == 'boundary':
899 newparams.append(('boundary', '"%s"' % boundary))
900 foundp = True
901 else:
902 newparams.append((pk, pv))
903 if not foundp:
904 # The original Content-Type header had no boundary attribute.
905 # Tack one on the end. BAW: should we raise an exception
906 # instead???
907 newparams.append(('boundary', '"%s"' % boundary))
908 # Replace the existing Content-Type header with the new value
909 newheaders = []
910 for h, v in self._headers:
911 if h.lower() == 'content-type':
912 parts = []
913 for k, v in newparams:
914 if v == '':
915 parts.append(k)
916 else:
917 parts.append('%s=%s' % (k, v))
918 val = SEMISPACE.join(parts)
919 newheaders.append(self.policy.header_store_parse(h, val))
920
921 else:
922 newheaders.append((h, v))
923 self._headers = newheaders
924
925 def get_content_charset(self, failobj=None):
926 """Return the charset parameter of the Content-Type header.
927
928 The returned string is always coerced to lower case. If there is no
929 Content-Type header, or if that header has no charset parameter,
930 failobj is returned.
931 """
932 missing = object()
933 charset = self.get_param('charset', missing)
934 if charset is missing:
935 return failobj
936 if isinstance(charset, tuple):
937 # RFC 2231 encoded, so decode it, and it better end up as ascii.
938 pcharset = charset[0] or 'us-ascii'
939 try:
940 # LookupError will be raised if the charset isn't known to
941 # Python. UnicodeError will be raised if the encoded text
942 # contains a character not in the charset.
943 as_bytes = charset[2].encode('raw-unicode-escape')
944 charset = str(as_bytes, pcharset)
945 except (LookupError, UnicodeError):
946 charset = charset[2]
947 # charset characters must be in us-ascii range
948 try:
949 charset.encode('us-ascii')
950 except UnicodeError:
951 return failobj
952 # RFC 2046, $4.1.2 says charsets are not case sensitive
953 return charset.lower()
954
955 def get_charsets(self, failobj=None):
956 """Return a list containing the charset(s) used in this message.
957
958 The returned list of items describes the Content-Type headers'
959 charset parameter for this message and all the subparts in its
960 payload.
961
962 Each item will either be a string (the value of the charset parameter
963 in the Content-Type header of that part) or the value of the
964 'failobj' parameter (defaults to None), if the part does not have a
965 main MIME type of "text", or the charset is not defined.
966
967 The list will contain one string for each part of the message, plus
968 one for the container message (i.e. self), so that a non-multipart
969 message will still return a list of length 1.
970 """
971 return [part.get_content_charset(failobj) for part in self.walk()]
972
973 def get_content_disposition(self):
974 """Return the message's content-disposition if it exists, or None.
975
976 The return values can be either 'inline', 'attachment' or None
977 according to the rfc2183.
978 """
979 value = self.get('content-disposition')
980 if value is None:
981 return None
982 c_d = _splitparam(value)[0].lower()
983 return c_d
984
985 # I.e. def walk(self): ...
986 from email.iterators import walk
987
988
989 class MIMEPart(Message):
990
991 def __init__(self, policy=None):
992 if policy is None:
993 from email.policy import default
994 policy = default
995 super().__init__(policy)
996
997
998 def as_string(self, unixfrom=False, maxheaderlen=None, policy=None):
999 """Return the entire formatted message as a string.
1000
1001 Optional 'unixfrom', when true, means include the Unix From_ envelope
1002 header. maxheaderlen is retained for backward compatibility with the
1003 base Message class, but defaults to None, meaning that the policy value
1004 for max_line_length controls the header maximum length. 'policy' is
1005 passed to the Generator instance used to serialize the message; if it
1006 is not specified the policy associated with the message instance is
1007 used.
1008 """
1009 policy = self.policy if policy is None else policy
1010 if maxheaderlen is None:
1011 maxheaderlen = policy.max_line_length
1012 return super().as_string(unixfrom, maxheaderlen, policy)
1013
1014 def __str__(self):
1015 return self.as_string(policy=self.policy.clone(utf8=True))
1016
1017 def is_attachment(self):
1018 c_d = self.get('content-disposition')
1019 return False if c_d is None else c_d.content_disposition == 'attachment'
1020
1021 def _find_body(self, part, preferencelist):
1022 if part.is_attachment():
1023 return
1024 maintype, subtype = part.get_content_type().split('/')
1025 if maintype == 'text':
1026 if subtype in preferencelist:
1027 yield (preferencelist.index(subtype), part)
1028 return
1029 if maintype != 'multipart' or not self.is_multipart():
1030 return
1031 if subtype != 'related':
1032 for subpart in part.iter_parts():
1033 yield from self._find_body(subpart, preferencelist)
1034 return
1035 if 'related' in preferencelist:
1036 yield (preferencelist.index('related'), part)
1037 candidate = None
1038 start = part.get_param('start')
1039 if start:
1040 for subpart in part.iter_parts():
1041 if subpart['content-id'] == start:
1042 candidate = subpart
1043 break
1044 if candidate is None:
1045 subparts = part.get_payload()
1046 candidate = subparts[0] if subparts else None
1047 if candidate is not None:
1048 yield from self._find_body(candidate, preferencelist)
1049
1050 def get_body(self, preferencelist=('related', 'html', 'plain')):
1051 """Return best candidate mime part for display as 'body' of message.
1052
1053 Do a depth first search, starting with self, looking for the first part
1054 matching each of the items in preferencelist, and return the part
1055 corresponding to the first item that has a match, or None if no items
1056 have a match. If 'related' is not included in preferencelist, consider
1057 the root part of any multipart/related encountered as a candidate
1058 match. Ignore parts with 'Content-Disposition: attachment'.
1059 """
1060 best_prio = len(preferencelist)
1061 body = None
1062 for prio, part in self._find_body(self, preferencelist):
1063 if prio < best_prio:
1064 best_prio = prio
1065 body = part
1066 if prio == 0:
1067 break
1068 return body
1069
1070 _body_types = {('text', 'plain'),
1071 ('text', 'html'),
1072 ('multipart', 'related'),
1073 ('multipart', 'alternative')}
1074 def iter_attachments(self):
1075 """Return an iterator over the non-main parts of a multipart.
1076
1077 Skip the first of each occurrence of text/plain, text/html,
1078 multipart/related, or multipart/alternative in the multipart (unless
1079 they have a 'Content-Disposition: attachment' header) and include all
1080 remaining subparts in the returned iterator. When applied to a
1081 multipart/related, return all parts except the root part. Return an
1082 empty iterator when applied to a multipart/alternative or a
1083 non-multipart.
1084 """
1085 maintype, subtype = self.get_content_type().split('/')
1086 if maintype != 'multipart' or subtype == 'alternative':
1087 return
1088 payload = self.get_payload()
1089 # Certain malformed messages can have content type set to `multipart/*`
1090 # but still have single part body, in which case payload.copy() can
1091 # fail with AttributeError.
1092 try:
1093 parts = payload.copy()
1094 except AttributeError:
1095 # payload is not a list, it is most probably a string.
1096 return
1097
1098 if maintype == 'multipart' and subtype == 'related':
1099 # For related, we treat everything but the root as an attachment.
1100 # The root may be indicated by 'start'; if there's no start or we
1101 # can't find the named start, treat the first subpart as the root.
1102 start = self.get_param('start')
1103 if start:
1104 found = False
1105 attachments = []
1106 for part in parts:
1107 if part.get('content-id') == start:
1108 found = True
1109 else:
1110 attachments.append(part)
1111 if found:
1112 yield from attachments
1113 return
1114 parts.pop(0)
1115 yield from parts
1116 return
1117 # Otherwise we more or less invert the remaining logic in get_body.
1118 # This only really works in edge cases (ex: non-text related or
1119 # alternatives) if the sending agent sets content-disposition.
1120 seen = [] # Only skip the first example of each candidate type.
1121 for part in parts:
1122 maintype, subtype = part.get_content_type().split('/')
1123 if ((maintype, subtype) in self._body_types and
1124 not part.is_attachment() and subtype not in seen):
1125 seen.append(subtype)
1126 continue
1127 yield part
1128
1129 def iter_parts(self):
1130 """Return an iterator over all immediate subparts of a multipart.
1131
1132 Return an empty iterator for a non-multipart.
1133 """
1134 if self.is_multipart():
1135 yield from self.get_payload()
1136
1137 def get_content(self, *args, content_manager=None, **kw):
1138 if content_manager is None:
1139 content_manager = self.policy.content_manager
1140 return content_manager.get_content(self, *args, **kw)
1141
1142 def set_content(self, *args, content_manager=None, **kw):
1143 if content_manager is None:
1144 content_manager = self.policy.content_manager
1145 content_manager.set_content(self, *args, **kw)
1146
1147 def _make_multipart(self, subtype, disallowed_subtypes, boundary):
1148 if self.get_content_maintype() == 'multipart':
1149 existing_subtype = self.get_content_subtype()
1150 disallowed_subtypes = disallowed_subtypes + (subtype,)
1151 if existing_subtype in disallowed_subtypes:
1152 raise ValueError("Cannot convert {} to {}".format(
1153 existing_subtype, subtype))
1154 keep_headers = []
1155 part_headers = []
1156 for name, value in self._headers:
1157 if name.lower().startswith('content-'):
1158 part_headers.append((name, value))
1159 else:
1160 keep_headers.append((name, value))
1161 if part_headers:
1162 # There is existing content, move it to the first subpart.
1163 part = type(self)(policy=self.policy)
1164 part._headers = part_headers
1165 part._payload = self._payload
1166 self._payload = [part]
1167 else:
1168 self._payload = []
1169 self._headers = keep_headers
1170 self['Content-Type'] = 'multipart/' + subtype
1171 if boundary is not None:
1172 self.set_param('boundary', boundary)
1173
1174 def make_related(self, boundary=None):
1175 self._make_multipart('related', ('alternative', 'mixed'), boundary)
1176
1177 def make_alternative(self, boundary=None):
1178 self._make_multipart('alternative', ('mixed',), boundary)
1179
1180 def make_mixed(self, boundary=None):
1181 self._make_multipart('mixed', (), boundary)
1182
1183 def _add_multipart(self, _subtype, *args, _disp=None, **kw):
1184 if (self.get_content_maintype() != 'multipart' or
1185 self.get_content_subtype() != _subtype):
1186 getattr(self, 'make_' + _subtype)()
1187 part = type(self)(policy=self.policy)
1188 part.set_content(*args, **kw)
1189 if _disp and 'content-disposition' not in part:
1190 part['Content-Disposition'] = _disp
1191 self.attach(part)
1192
1193 def add_related(self, *args, **kw):
1194 self._add_multipart('related', *args, _disp='inline', **kw)
1195
1196 def add_alternative(self, *args, **kw):
1197 self._add_multipart('alternative', *args, **kw)
1198
1199 def add_attachment(self, *args, **kw):
1200 self._add_multipart('mixed', *args, _disp='attachment', **kw)
1201
1202 def clear(self):
1203 self._headers = []
1204 self._payload = None
1205
1206 def clear_content(self):
1207 self._headers = [(n, v) for n, v in self._headers
1208 if not n.lower().startswith('content-')]
1209 self._payload = None
1210
1211
1212 class EmailMessage(MIMEPart):
1213
1214 def set_content(self, *args, **kw):
1215 super().set_content(*args, **kw)
1216 if 'MIME-Version' not in self:
1217 self['MIME-Version'] = '1.0'