[Python-checkins] cpython (3.1): #11216: document all possible set_charset execution paths.

[r.david.murray]

http://hg.python.org/cpython/rev/cf1859f9aed9
changeset:   68560:cf1859f9aed9
branch:      3.1
parent:      68550:de5638f399a2
user:        R David Murray <rdmurray at bitdance.com>
date:        Tue Mar 15 17:41:13 2011 -0400
summary:
  #11216: document all possible set_charset execution paths.

files:
  Doc/library/email.message.rst

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
@@ -130,15 +130,22 @@
       string naming a character set, or ``None``.  If it is a string, it will
       be converted to a :class:`~email.charset.Charset` instance.  If *charset*
       is ``None``, the ``charset`` parameter will be removed from the
-      :mailheader:`Content-Type` header. Anything else will generate a
-      :exc:`TypeError`.
+      :mailheader:`Content-Type` header (the message will not be otherwise
+      modified).  Anything else will generate a :exc:`TypeError`.
 
-      The message will be assumed to be of type :mimetype:`text/\*` encoded with
-      *charset.input_charset*.  It will be converted to *charset.output_charset*
-      and encoded properly, if needed, when generating the plain text
-      representation of the message.  MIME headers (:mailheader:`MIME-Version`,
-      :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will
-      be added as needed.
+      If there is no existing :mailheader:`MIME-Version` header one will be
+      added.  If there is no existing :mailheader:`Content-Type` header, one
+      will be added with a value of :mimetype:`text/plain`.  Whether the
+      :mailheader:`Content-Type` header already exists or not, its ``charset``
+      parameter will be set to *charset.output_charset*.   If
+      *charset.input_charset* and *charset.output_charset* differ, the payload
+      will be re-encoded to the *output_charset*.  If there is no existing
+      :mailheader:`Content-Transfer-Encoding` header, then the payload will be
+      transfer-encoded, if needed, using the specified
+      :class:`~email.charset.Charset`, and a header with the appropriate value
+      will be added.  If a :mailheader:`Content-Transfer-Encoding` header
+      already exists, the payload is assumed to already be correctly encoded
+      using that :mailheader:`Content-Transfer-Encoding` and is not modified.
 
    .. method:: get_charset()
 

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