[Python-checkins] cpython (3.4): #18854: make it explicit that is_multipart does not mean 'multipart/xxx'.

[r.david.murray]

https://hg.python.org/cpython/rev/b717128799b5
changeset:   92600:b717128799b5
branch:      3.4
parent:      92598:2eea52c287b7
user:        R David Murray <rdmurray at bitdance.com>
date:        Sat Sep 27 15:37:40 2014 -0400
summary:
  #18854: make it explicit that is_multipart does not mean 'multipart/xxx'.

Original patch (and the idea of using _structure) by Abhilash Raj.

files:
  Doc/library/email.message.rst |  67 +++++++++++++++++-----
  1 files changed, 52 insertions(+), 15 deletions(-)


diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -131,7 +131,11 @@
 
       Return ``True`` if the message's payload is a list of sub-\
       :class:`Message` objects, otherwise return ``False``.  When
-      :meth:`is_multipart` returns ``False``, the payload should be a string object.
+      :meth:`is_multipart` returns ``False``, the payload should be a string
+      object.  (Note that :meth:`is_multipart` returning ``True`` does not
+      necessarily mean that "msg.get_content_maintype() == 'multipart'" will
+      return the ``True``.   For example, ``is_multipart`` will return ``True``
+      when the :class:`Message` is of type ``message/rfc822``.)
 
 
    .. method:: set_unixfrom(unixfrom)
@@ -584,23 +588,56 @@
       Here's an example that prints the MIME type of every part of a multipart
       message structure:
 
-       .. testsetup::
+      .. testsetup::
 
-            >>> from email import message_from_binary_file
-            >>> with open('Lib/test/test_email/data/msg_16.txt', 'rb') as f:
-            ...     msg = message_from_binary_file(f)
+         >>> from email import message_from_binary_file
+         >>> with open('Lib/test/test_email/data/msg_16.txt', 'rb') as f:
+         ...     msg = message_from_binary_file(f)
+         >>> from email.iterators import _structure
 
-       .. doctest::
+      .. doctest::
 
-            >>> for part in msg.walk():
-            ...     print(part.get_content_type())
-            multipart/report
-            text/plain
-            message/delivery-status
-            text/plain
-            text/plain
-            message/rfc822
-            text/plain
+         >>> for part in msg.walk():
+         ...     print(part.get_content_type())
+         multipart/report
+         text/plain
+         message/delivery-status
+         text/plain
+         text/plain
+         message/rfc822
+         text/plain
+
+      ``walk`` iterates over the subparts of any part where
+      :meth:`is_multipart` returns ``True``, even though
+      ``msg.get_content_maintype() == 'multipart'`` may return ``False``.  We
+      can see this in our example by making use of the ``_structure`` debug
+      helper function:
+
+      .. doctest::
+
+         >>> for part in msg.walk():
+         ...     print(part.get_content_maintype() == 'multipart'),
+         ...           part.is_multipart())
+         True True
+         False False
+         False True
+         False False
+         False False
+         False True
+         False False
+         >>> _structure(msg)
+         multipart/report
+             text/plain
+         message/delivery-status
+             text/plain
+             text/plain
+         message/rfc822
+             text/plain
+
+      Here the ``message`` parts are not ``multiparts``, but they do contain
+      subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends
+      into the subparts.
+
 
    :class:`Message` objects can also optionally contain two instance attributes,
    which can be used when generating the plain text of a MIME message.

-- 
Repository URL: https://hg.python.org/cpython