Changeset 391 for python/trunk/Doc/library/email.mime.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/email.mime.rst (modified) (8 diffs)

python/trunk/Doc/library/email.mime.rst

@@ -1 @@
-:mod:`email`: Creating email and MIME objects from scratch
-----------------------------------------------------------
+:mod:`email.mime`: Creating email and MIME objects from scratch
+---------------------------------------------------------------
 
 .. module:: email.mime
@@ -36 +36 @@
    or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
    type  (e.g. :mimetype:`plain` or :mimetype:`gif`).  *_params* is a parameter
-   key/value dictionary and is passed directly to :meth:`Message.add_header`.
+   key/value dictionary and is passed directly to :meth:`Message.add_header
+   <email.message.Message.add_header>`.
 
    The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
@@ -51 +52 @@
    A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
    class for MIME messages that are not :mimetype:`multipart`.  The primary
-   purpose of this class is to prevent the use of the :meth:`attach` method,
-   which only makes sense for :mimetype:`multipart` messages.  If :meth:`attach`
+   purpose of this class is to prevent the use of the
+   :meth:`~email.message.Message.attach` method, which only makes sense for
+   :mimetype:`multipart` messages.  If :meth:`~email.message.Message.attach`
    is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
 
@@ -77 +79 @@
    *_subparts* is a sequence of initial subparts for the payload.  It must be
    possible to convert this sequence to a list.  You can always attach new subparts
-   to the message by using the :meth:`Message.attach` method.
+   to the message by using the :meth:`Message.attach
+   <email.message.Message.attach>` method.
 
    Additional parameters for the :mailheader:`Content-Type` header are taken from
@@ -100 +103 @@
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the data for transport.  This callable takes one argument, which is
-   the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and
-   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   the :class:`MIMEApplication` instance. It should use
+   :meth:`~email.message.Message.get_payload` and
+   :meth:`~email.message.Message.set_payload` to change the payload to encoded
+   form.  It should also add
    any :mailheader:`Content-Transfer-Encoding` or other headers to the message
    object as necessary.  The default encoding is base64.  See the
@@ -128 +133 @@
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the audio data for transport.  This callable takes one argument,
-   which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and
-   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   which is the :class:`MIMEAudio` instance. It should use
+   :meth:`~email.message.Message.get_payload` and
+   :meth:`~email.message.Message.set_payload` to change the payload to encoded
+   form.  It should also add
    any :mailheader:`Content-Transfer-Encoding` or other headers to the message
    object as necessary.  The default encoding is base64.  See the
@@ -154 +161 @@
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the image data for transport.  This callable takes one argument,
-   which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and
-   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   which is the :class:`MIMEImage` instance. It should use
+   :meth:`~email.message.Message.get_payload` and
+   :meth:`~email.message.Message.set_payload` to change the payload to encoded
+   form.  It should also add
    any :mailheader:`Content-Transfer-Encoding` or other headers to the message
    object as necessary.  The default encoding is base64.  See the
@@ -192 +201 @@
    set of the text and is passed as a parameter to the
    :class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
-   to ``us-ascii``.  No guessing or encoding is performed on the text data.
+   to ``us-ascii``.  If *_text* is unicode, it is encoded using the
+   *output_charset* of *_charset*, otherwise it is used as-is.
 
    .. versionchanged:: 2.4
-      The previously deprecated *_encoding* argument has been removed.  Encoding
-      happens implicitly based on the *_charset* argument.
-
+      The previously deprecated *_encoding* argument has been removed.  Content
+      Transfer Encoding now happens implicitly based on the *_charset*
+      argument.
+
+   Unless the ``_charset`` parameter is explicitly set to ``None``, the
+   MIMEText object created will have both a :mailheader:`Content-Type` header
+   with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Endcoding`
+   header.  This means that a subsequent ``set_payload`` call will not result
+   in an encoded payload, even if a charset is passed in the ``set_payload``
+   command.  You can "reset" this behavior by deleting the
+   ``Content-Transfer-Encoding`` header, after which a ``set_payload`` call
+   will automatically encode the new payload (and add a new
+   :mailheader:`Content-Transfer-Encoding` header).