Master patch for content manager addition to email package

[bitdancer]

BPO	18891
Nosy	@warsaw, @bitdancer, @yaseppochi, @ericsnowcurrently, @serhiy-storchaka
Files	master_content_manager.patch master_content_manager.patch master_content_manager.patch master_content_manager.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-02-01.22:50:01.998>
created_at = <Date 2013-08-31.03:10:03.700>
labels = ['type-feature', 'expert-email']
title = 'Master patch for content manager addition to email package'
updated_at = <Date 2014-02-01.22:50:01.996>
user = 'https://github.com/bitdancer'

bugs.python.org fields:

activity = <Date 2014-02-01.22:50:01.996>
actor = 'r.david.murray'
assignee = 'none'
closed = True
closed_date = <Date 2014-02-01.22:50:01.998>
closer = 'r.david.murray'
components = ['email']
creation = <Date 2013-08-31.03:10:03.700>
creator = 'r.david.murray'
dependencies = []
files = ['31529', '32024', '32055', '32069']
hgrepos = []
issue_num = 18891
keywords = ['patch']
message_count = 11.0
messages = ['196613', '196825', '196847', '196864', '199344', '199535', '199625', '200105', '200106', '200129', '209925']
nosy_count = 6.0
nosy_names = ['barry', 'r.david.murray', 'sjt', 'python-dev', 'eric.snow', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue18891'
versions = ['Python 3.4']

[bitdancer]

Since the only way to get a rietveld review link for all the changes is to post a single complete patch, I'm doing so in this issue. Feel free to review based on either this or the separate patches posted in bpo-18785, bpo-18860, and bpo-18890.

There are a couple of bug fixes in this code, but for the most part it is the addition of a new sub-modulej, and a new subclass to the message.py code, plus the accompanying documentation.

Note that this pretty much completes the proposed API additions to the email module. There may be some additional small tweaks, and there will certainly be some additional support code for specific message header and message types later, but checking this in will mark the completion of the email6 implementation from my point of view. (The project won't be complete, of course, until the code becomes non-provisional, hopefully in 3.5.)

[yaseppochi]

I'm thinking this may be overengineering, but I may as well post it and find out for sure. :-) Is it worth encapsulating MIME types? They're "really" pairs as far as mail handling applications are concerned, but they have a string representation. So

MacPorts 16:29$ python3.3
Python 3.3.2 (default, May 21 2013, 11:48:51) 
>>> from collections import namedtuple
>>> class MIMEType(namedtuple('MIMETYPE', 'type subtype')):
...  def __str__(self):
...   return "{0}/{1}".format(self.type, self.subtype)
... 
>>> mt = MIMEType('text', 'plain')
>>> str(mt)
'text/plain'
>>> t, s = mt
>>> print('type =', t, 'subtype =', s)
type = text subtype = plain
>>> 

Obviously there needs to be a constructor that handles the 'type/sub' represention.

[bitdancer]

It's an interesting thought. It bothered me to be handling them as pure strings when writing the code. It just felt wrong somehow :)

[warsaw]

On Sep 03, 2013, at 07:37 AM, Stephen J. Turnbull wrote:

I'm thinking this may be overengineering, but I may as well post it and find
out for sure. :-) Is it worth encapsulating MIME types? They're "really"
pairs as far as mail handling applications are concerned, but they have a
string representation.

Neat idea.

[bitdancer]

Updating the patch to address Stephen's review comments (thanks, Stephen!). The biggest change is adding a MIMEPart class, and renaming MIMEMessage to EmailMessage. Other significant changes are: only moving 'Content-*' headers in 'make' methods, adding 'clear' and 'clear_content' methods (and calling clear_content in the 'make' methods), and raising a TypeError if set_content is called on a multipart.

The documentation is complete, but not completely proofread/edited. I can always finish that after the Beta if I don't get to it before (though I expect to). There are probably some missing docstrings as well; same comment applies :).

I have not addressed the MIMEType idea. I will deal with that as a separate issue (and not for 3.4), since it has implications throughout the package, not just in the code I'm enhancing.

I think this is ready for commit review, assuming I haven't forgotten anything. (I'll close the earlier issues.)

[bitdancer]

Final doc edits done. I will commit this next week if there are no objections, in order to get it in to alpha 4.

[bitdancer]

Updated patch to address Serhiy's review comments. Also noticed a bug and fixed it, adding a new 'is_attachment' attribute to EmailMessage/MIMEPart to do so.

[python-dev]

New changeset 6d12285e250b by R David Murray in branch 'default':
bpo-18891: Complete new provisional email API.
http://hg.python.org/cpython/rev/6d12285e250b

[ericsnowcurrently]

nice! Thanks for doing this.

[bitdancer]

Thanks everyone for the reviews. I've opened up a new issue for Stephen's mimetype object suggestion (bpo-19280).

I'm still planning to add some examples to the docs, so I'm going to leave this open until I do that, but I wanted to get the code itself into the next alpha.

[bitdancer]

Opened bpo-20477 with the proposed examples.