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