Big email 3.0 API changes, with updated unit tests and documentation.
Briefly (from the NEWS file):
- Updates for the email package:
+ All deprecated APIs that in email 2.x issued warnings have been removed:
_encoder argument to the MIMEText constructor, Message.add_payload(),
Utils.dump_address_pair(), Utils.decode(), Utils.encode()
+ New deprecations: Generator.__call__(), Message.get_type(),
Message.get_main_type(), Message.get_subtype(), the 'strict' argument to
the Parser constructor. These will be removed in email 3.1.
+ Support for Python earlier than 2.3 has been removed (see PEP 291).
+ All defect classes have been renamed to end in 'Defect'.
+ Some FeedParser fixes; also a MultipartInvariantViolationDefect will be
added to messages that claim to be multipart but really aren't.
+ Updates to documentation.
diff --git a/Lib/email/Message.py b/Lib/email/Message.py
index 2245f9b..d23a26f 100644
--- a/Lib/email/Message.py
+++ b/Lib/email/Message.py
@@ -1,5 +1,6 @@
# Copyright (C) 2001-2004 Python Software Foundation
-# Author: barry@python.org (Barry Warsaw)
+# Author: Barry Warsaw
+# Contact: email-sig@python.org
"""Basic message object for the email package object model."""
@@ -69,6 +70,10 @@
def _unquotevalue(value):
+ # This is different than Utils.collapse_rfc2231_value() because it doesn't
+ # try to convert the value to a unicode. Message.get_param() and
+ # Message.get_params() are both currently defined to return the tuple in
+ # the face of RFC 2231 parameters.
if isinstance(value, tuple):
return value[0], value[1], Utils.unquote(value[2])
else:
@@ -98,6 +103,7 @@
self._charset = None
# Defaults for multipart messages
self.preamble = self.epilogue = None
+ self.defects = []
# Default content type
self._default_type = 'text/plain'
@@ -124,9 +130,7 @@
def is_multipart(self):
"""Return True if the message consists of multiple parts."""
- if isinstance(self._payload, list):
- return True
- return False
+ return isinstance(self._payload, list)
#
# Unix From_ line
@@ -140,26 +144,6 @@
#
# Payload manipulation.
#
- def add_payload(self, payload):
- """Add the given payload to the current payload.
-
- If the current payload is empty, then the current payload will be made
- a scalar, set to the given value.
-
- Note: This method is deprecated. Use .attach() instead.
- """
- warnings.warn('add_payload() is deprecated, use attach() instead.',
- DeprecationWarning, 2)
- if self._payload is None:
- self._payload = payload
- elif isinstance(self._payload, list):
- self._payload.append(payload)
- elif self.get_main_type() not in (None, 'multipart'):
- raise Errors.MultipartConversionError(
- 'Message main content type must be "multipart" or missing')
- else:
- self._payload = [self._payload, payload]
-
def attach(self, payload):
"""Add the given payload to the current payload.
@@ -195,7 +179,7 @@
if i is None:
payload = self._payload
elif not isinstance(self._payload, list):
- raise TypeError, 'Expected list, got %s' % type(self._payload)
+ raise TypeError('Expected list, got %s' % type(self._payload))
else:
payload = self._payload[i]
if decode:
@@ -254,7 +238,7 @@
if isinstance(charset, str):
charset = Charset.Charset(charset)
if not isinstance(charset, Charset.Charset):
- raise TypeError, charset
+ raise TypeError(charset)
# BAW: should we accept strings that can serve as arguments to the
# Charset constructor?
self._charset = charset
@@ -267,9 +251,9 @@
self.set_param('charset', charset.get_output_charset())
if not self.has_key('Content-Transfer-Encoding'):
cte = charset.get_body_encoding()
- if callable(cte):
+ try:
cte(self)
- else:
+ except TypeError:
self.add_header('Content-Transfer-Encoding', cte)
def get_charset(self):
@@ -290,7 +274,7 @@
Return None if the header is missing instead of raising an exception.
Note that if the header appeared multiple times, exactly which
- occurrance gets returned is undefined. Use getall() to get all
+ occurrance gets returned is undefined. Use get_all() to get all
the values matching a header field name.
"""
return self.get(name)
@@ -320,7 +304,7 @@
def has_key(self, name):
"""Return true if the message contains the header."""
- missing = []
+ missing = object()
return self.get(name, missing) is not missing
def keys(self):
@@ -422,11 +406,10 @@
self._headers[i] = (k, _value)
break
else:
- raise KeyError, _name
+ raise KeyError(_name)
#
- # These methods are silently deprecated in favor of get_content_type() and
- # friends (see below). They will be noisily deprecated in email 3.0.
+ # Deprecated methods. These will be removed in email 3.1.
#
def get_type(self, failobj=None):
@@ -436,7 +419,9 @@
string of the form `maintype/subtype'. If there was no Content-Type
header in the message, failobj is returned (defaults to None).
"""
- missing = []
+ warnings.warn('get_type() deprecated; use get_content_type()',
+ DeprecationWarning, 2)
+ missing = object()
value = self.get('content-type', missing)
if value is missing:
return failobj
@@ -444,7 +429,9 @@
def get_main_type(self, failobj=None):
"""Return the message's main content type if present."""
- missing = []
+ warnings.warn('get_main_type() deprecated; use get_content_maintype()',
+ DeprecationWarning, 2)
+ missing = object()
ctype = self.get_type(missing)
if ctype is missing:
return failobj
@@ -454,7 +441,9 @@
def get_subtype(self, failobj=None):
"""Return the message's content subtype if present."""
- missing = []
+ warnings.warn('get_subtype() deprecated; use get_content_subtype()',
+ DeprecationWarning, 2)
+ missing = object()
ctype = self.get_type(missing)
if ctype is missing:
return failobj
@@ -479,7 +468,7 @@
appears inside a multipart/digest container, in which case it would be
message/rfc822.
"""
- missing = []
+ missing = object()
value = self.get('content-type', missing)
if value is missing:
# This should have no parameters
@@ -529,7 +518,7 @@
def _get_params_preserve(self, failobj, header):
# Like get_params() but preserves the quoting of values. BAW:
# should this be part of the public interface?
- missing = []
+ missing = object()
value = self.get(header, missing)
if value is missing:
return failobj
@@ -560,7 +549,7 @@
header. Optional header is the header to search instead of
Content-Type. If unquote is True, the value is unquoted.
"""
- missing = []
+ missing = object()
params = self._get_params_preserve(missing, header)
if params is missing:
return failobj
@@ -713,17 +702,11 @@
The filename is extracted from the Content-Disposition header's
`filename' parameter, and it is unquoted.
"""
- missing = []
+ missing = object()
filename = self.get_param('filename', missing, 'content-disposition')
if filename is missing:
return failobj
- if isinstance(filename, tuple):
- # It's an RFC 2231 encoded parameter
- newvalue = _unquotevalue(filename)
- return unicode(newvalue[2], newvalue[0] or 'us-ascii')
- else:
- newvalue = _unquotevalue(filename.strip())
- return newvalue
+ return Utils.collapse_rfc2231_value(filename).strip()
def get_boundary(self, failobj=None):
"""Return the boundary associated with the payload if present.
@@ -731,15 +714,11 @@
The boundary is extracted from the Content-Type header's `boundary'
parameter, and it is unquoted.
"""
- missing = []
+ missing = object()
boundary = self.get_param('boundary', missing)
if boundary is missing:
return failobj
- if isinstance(boundary, tuple):
- # RFC 2231 encoded, so decode. It better end up as ascii
- charset = boundary[0] or 'us-ascii'
- return unicode(boundary[2], charset).encode('us-ascii')
- return _unquotevalue(boundary.strip())
+ return Utils.collapse_rfc2231_value(boundary).strip()
def set_boundary(self, boundary):
"""Set the boundary parameter in Content-Type to 'boundary'.
@@ -751,7 +730,7 @@
HeaderParseError is raised if the message has no Content-Type header.
"""
- missing = []
+ missing = object()
params = self._get_params_preserve(missing, 'content-type')
if params is missing:
# There was no Content-Type header, and we don't know what type
@@ -793,7 +772,7 @@
Content-Type header, or if that header has no charset parameter,
failobj is returned.
"""
- missing = []
+ missing = object()
charset = self.get_param('charset', missing)
if charset is missing:
return failobj