classification
Title: is_multipart and walk should document their treatment of 'message' parts.
Type: behavior Stage: resolved
Components: email Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: r.david.murray Nosy List: abhilash.raj, barry, nitika, python-dev, r.david.murray
Priority: normal Keywords: patch

Created on 2013-08-27 14:05 by r.david.murray, last changed 2014-09-27 19:39 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
email.patch abhilash.raj, 2014-05-07 18:16 review
email-1.patch abhilash.raj, 2014-05-07 20:19 review
Messages (12)
msg196292 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-08-27 14:05
A 'message' part is not, in fact, a multipart in RFC terms.  (Only 'multipart' messages are multiparts.)  The email package models 'message' parts by making them single-element "multipart" messages, with the single element being a Message object representing the 'message' part's payload.

This is very useful; however, the fact that this is done should be documented in at least the is_multipart and walk methods.  As motivation for documenting this, consider a program that is looking for "the first part of type X" in a Message.  If an attached 'message' object has such a part, it would be discovered by a naive algorithm that uses 'walk', even though it is *inside* an attachment instead of part of the main message.  As for is_multipart, a naive reader of the documentation might expect that is_multipart would be true if and only if get_content_maintype == 'multipart', when this is in fact not true.

(I made these mistakes myself while implementing get_body and iter_parts in the new API additions.)
msg213297 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-12 21:01
Hi David,
Will you please help me with the link?
msg213299 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-12 21:08
If you are asking which documentation needs to be updated, it is:

   Doc/library/email.message.rst

The descriptions of the is_multipart method and the walk method.
msg213711 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-16 04:44
Hello everyone,
I am working on this issue to create a patch.
msg213740 - (view) Author: Nitika Agarwal (nitika) * Date: 2014-03-16 17:19
Hi David,
I didn't exactly get the issue.Will you please help me with what is to be updated.
msg213747 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-16 18:34
Well, probably the best thing to do to understand the issue is to look at the implementation of Message.walk and is_multipart, and to notice that "is_multipart()" can return a different answer than "msg.get_content_maintype() == 'multipart'" if the Message content type is "message/rfc822".  You may want to do some reading about how to construct Messages and experiment by creating such a message/rfc822 Message to really understand it.
msg218068 - (view) Author: Abhilash Raj (abhilash.raj) * Date: 2014-05-07 18:16
I have tried to document the issue in the patch as discussed.

David: Do you think I should also add an example in walk() method
to demonstrate that it does not iterate over a 'message/rfc822' part
even though it is multipart?
msg218070 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-05-07 18:35
Take a look at the source for msg_16.txt.  The last part is a message/rfc822, which encapsulates a text/plain message.  So it *does* iterate over it, even though it isn't a 'multipart' type (the opposite of what you say in the doc patch).

Explicitly pointing out this aspect of the existing example would be a good idea.
msg218073 - (view) Author: Abhilash Raj (abhilash.raj) * Date: 2014-05-07 20:19
Sorry, my bad. I was a little confused. I have updated the patch and
also added the example explicitly.
msg218075 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-05-07 20:47
Using _structure is a great idea.  I'm not so fond of the full example, but I'll have to contemplate the text to decide what I'd rather do.  Probably I'll take this patch of yours and tweak it, rather than try to tell you what I want :)  Thanks for the patch!
msg227715 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-09-27 19:38
New changeset b717128799b5 by R David Murray in branch '3.4':
#18854: make it explicit that is_multipart does not mean 'multipart/xxx'.
https://hg.python.org/cpython/rev/b717128799b5

New changeset 9909de463dc9 by R David Murray in branch 'default':
Merge: #18854: make it explicit that is_multipart does not mean 'multipart/xxx'.
https://hg.python.org/cpython/rev/9909de463dc9
msg227716 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-09-27 19:39
Thanks Abhilash.  I decided to use the full example after all, but tuned up the language a bit.
History
Date User Action Args
2014-09-27 19:39:55r.david.murraysetstatus: open -> closed
versions: + Python 3.5, - Python 3.3
type: behavior
messages: + msg227716

resolution: fixed
stage: commit review -> resolved
2014-09-27 19:38:46python-devsetnosy: + python-dev
messages: + msg227715
2014-05-07 20:47:48r.david.murraysetassignee: r.david.murray
messages: + msg218075
stage: needs patch -> commit review
2014-05-07 20:19:23abhilash.rajsetfiles: + email-1.patch

messages: + msg218073
2014-05-07 18:35:57r.david.murraysetmessages: + msg218070
2014-05-07 18:16:44abhilash.rajsetfiles: + email.patch

nosy: + abhilash.raj
messages: + msg218068

keywords: + patch
2014-03-16 18:34:53r.david.murraysetmessages: + msg213747
2014-03-16 17:19:11nitikasetmessages: + msg213740
2014-03-16 04:44:14nitikasetmessages: + msg213711
2014-03-12 21:08:17r.david.murraysetmessages: + msg213299
2014-03-12 21:01:18nitikasetnosy: + nitika
messages: + msg213297
2013-08-27 14:05:12r.david.murraycreate