cpython-lru_cache-weakref: Lib/email/message.py annotate

annotate Lib/email/message.py @ 58925:eecf1bef052d 2.6

Merged revisions 78207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78207 | ezio.melotti | 2010-02-17 01:26:09 +0200 (Wed, 17 Feb 2010) | 1 line #7930: fix stripid ........

author	Ezio Melotti <ezio.melotti@gmail.com>
date	Tue, 16 Feb 2010 23:29:44 +0000
parents	71574fe49576
children	450c69210581 684960fb1cbf

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

Mercurial > cpython-lru_cache-weakref

annotate Lib/email/message.py @ 58925:eecf1bef052d 2.6