[Python-checkins] cpython: whatsnew: Message.set_param *replace*, Policy.content_manager.

[r.david.murray]

http://hg.python.org/cpython/rev/4a3f74b3758c
changeset:   89563:4a3f74b3758c
user:        R David Murray <rdmurray at bitdance.com>
date:        Mon Mar 10 10:08:05 2014 -0400
summary:
  whatsnew: Message.set_param *replace*, Policy.content_manager.

Also cleaned up the email section and fixed some markup bugs in the
email docs.

files:
  Doc/library/email-examples.rst       |   6 +-
  Doc/library/email.contentmanager.rst |  19 ++++--
  Doc/library/email.message.rst        |   4 +-
  Doc/library/email.policy.rst         |   2 +-
  Doc/whatsnew/3.4.rst                 |  43 ++++++++-------
  5 files changed, 42 insertions(+), 32 deletions(-)


diff --git a/Doc/library/email-examples.rst b/Doc/library/email-examples.rst
--- a/Doc/library/email-examples.rst
+++ b/Doc/library/email-examples.rst
@@ -40,8 +40,10 @@
 .. literalinclude:: ../includes/email-alternative.py
 
 
-Examples using the Provision API
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _email-contentmanager-api-examples:
+
+Examples using the Provisional API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Here is a reworking of the last example using the provisional API.  To make
 things a bit more interesting, we include a related image in the html part, and
 we save a copy of what we are going to send to disk, as well as sending it.
diff --git a/Doc/library/email.contentmanager.rst b/Doc/library/email.contentmanager.rst
--- a/Doc/library/email.contentmanager.rst
+++ b/Doc/library/email.contentmanager.rst
@@ -54,6 +54,7 @@
    documented in this module because of the provisional nature of the code, the
    implementation lives in the :mod:`email.message` module.
 
+.. currentmodule:: email.message
 
 .. class:: EmailMessage(policy=default)
 
@@ -235,6 +236,16 @@
       all other headers intact and in their original order.
 
 
+.. class:: MIMEPart(policy=default)
+
+    This class represents a subpart of a MIME message.  It is identical to
+    :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
+    added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
+    not need their own :mailheader:`MIME-Version` headers.
+
+
+.. currentmodule:: email.contentmanager
+
 .. class:: ContentManager()
 
    Base class for content managers.  Provides the standard registry mechanisms
@@ -305,14 +316,6 @@
       values of *typekey*, see :meth:`set_content`.
 
 
-.. class:: MIMEPart(policy=default)
-
-    This class represents a subpart of a MIME message.  It is identical to
-    :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
-    added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
-    not need their own :mailheader:`MIME-Version` headers.
-
-
 Content Manager Instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
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
@@ -466,7 +466,7 @@
       to ``False``.
 
 
-   .. method:: set_param(param, value, header='Content-Type', requote=True,
+   .. method:: set_param(param, value, header='Content-Type', requote=True, \
                          charset=None, language='', replace=False)
 
       Set a parameter in the :mailheader:`Content-Type` header.  If the
@@ -488,7 +488,7 @@
       end of the list of headers.  If *replace* is ``True``, the header
       will be updated in place.
 
-      .. versionchanged: 3.4 ``replace`` keyword was added.
+      .. versionchanged:: 3.4 ``replace`` keyword was added.
 
 
    .. method:: del_param(param, header='content-type', requote=True)
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
--- a/Doc/library/email.policy.rst
+++ b/Doc/library/email.policy.rst
@@ -419,7 +419,7 @@
       additional arguments.  By default ``content_manager`` is set to
       :data:`~email.contentmanager.raw_data_manager`.
 
-      .. versionadded 3.4
+      .. versionadded:: 3.4
 
 
    The class provides the following concrete implementations of the abstract
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -731,7 +731,8 @@
 override the default policy of the message when generating a string
 representation of it.  This means that ``as_string`` can now be used in more
 circumstances, instead of having to create and use a :mod:`~email.generator` in
-order to pass formatting parameters to its ``flatten`` method.
+order to pass formatting parameters to its ``flatten`` method.  (Contributed by
+R. David Murray in :issue:`18600`.)
 
 New method :meth:`~email.message.Message.as_bytes` added to produce a bytes
 representation of the message in a fashion similar to how ``as_string``
@@ -739,26 +740,30 @@
 argument, but does accept the *unixfrom* and *policy* arguments. The
 :class:`~email.message.Message` :meth:`~email.message.Message.__bytes__` method
 calls it, meaning that ``bytes(mymsg)`` will now produce the intuitive
-result:  a bytes object containing the fully formatted message.
-
-(Contributed by R. David Murray in :issue:`18600`.)
+result:  a bytes object containing the fully formatted message.  (Contributed
+by R. David Murray in :issue:`18600`.)
+
+The :meth:`.Message.set_param` message now accepts a *replace* keyword argument.
+When specified, the associated header will be updated without changing
+its location in the list of headers.  For backward compatibility, the default
+is ``False``.  (Contributed by R. David Murray in :issue:`18891`.)
+
 
 .. _whatsnew_email_contentmanager:
 
-A pair of new subclasses of :class:`~email.message.Message` have been added,
-along with a new sub-module, :mod:`~email.contentmanager`.  All documentation
-is currently in the new module, which is being added as part of the new
-:term:`provisional <provisional package>` email API.  These classes provide a
-number of new methods that make extracting content from and inserting content
-into email messages much easier.  See the :mod:`~email.contentmanager`
-documentation for details.
-
-These API additions complete the bulk of the work that was planned as part of
-the email6 project.  The currently provisional API is scheduled to become final
-in Python 3.5 (possibly with a few minor additions in the area of error
-handling).
-
-(Contributed by R. David Murray in :issue:`18891`.)
+A pair of new subclasses of :class:`~email.message.Message` have been added
+(:class:`.EmailMessage` and :class:`.MIMEPart`), along with a new sub-module,
+:mod:`~email.contentmanager` and a new :mod:`~email.policy` attribute
+:attr:`~email.policy.EmailPolicy.content_manager`.  All documentation is
+currently in the new module, which is being added as part of email's new
+:term:`provisional API`.  These classes provide a number of new methods that
+make extracting content from and inserting content into email messages much
+easier.  For details, see the :mod:`~email.contentmanager` documentation and
+the :ref:`email-contentmanager-api-examples`.  These API additions complete the
+bulk of the work that was planned as part of the email6 project.  The currently
+provisional API is scheduled to become final in Python 3.5 (possibly with a few
+minor additions in the area of error handling).  (Contributed by R. David
+Murray in :issue:`18891`.)
 
 
 filecmp
@@ -1084,7 +1089,7 @@
 ---
 
 :mod:`pdb` has been enhanced to handle generators, :keyword:`yield`, and
-:keyword:`yield from` in a more useful fashion.  This is especially helpful when
+``yield from`` in a more useful fashion.  This is especially helpful when
 debugging :mod:`asyncio` based programs.  (Contributed by Andrew Svetlov and
 Xavier de Gaye in :issue:`16596`.)
 

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