whatsnew: Message.set_param *replace*, Policy.content_manager.

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

Doc/library/email-examples.rst

@@ -40,8 +40,10 @@ text version: [2]_
 .. 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.

Doc/library/email.contentmanager.rst

@@ -54,6 +54,7 @@ this module.
    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 @@ this module.
       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 @@ this module.
       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
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

Doc/library/email.message.rst

@@ -466,7 +466,7 @@ Here are the methods of the :class:`Message` class:
       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 @@ Here are the methods of the :class:`Message` class:
       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)

Doc/library/email.policy.rst

@@ -419,7 +419,7 @@ added matters.  To illustrate::
       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

Doc/whatsnew/3.4.rst

@@ -731,7 +731,8 @@ email
 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 @@ produces a string representation.  It does not accept the *maxheaderlen*
 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.
+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`.)
 
-(Contributed by R. David Murray in :issue:`18600`.)
 
 .. _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 @@ pdb
 ---
 
 :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`.)