Changeset 391 for python/trunk/Doc/library/email.message.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.message.rst (modified) (9 diffs)

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

@@ -1 @@
-:mod:`email`: Representing an email message
--------------------------------------------
+:mod:`email.message`: Representing an email message
+---------------------------------------------------
 
 .. module:: email.message
@@ -49 +49 @@
       format the message the way you want.  For example, by default it mangles
       lines that begin with ``From``.  For more flexibility, instantiate a
-      :class:`~email.generator.Generator` instance and use its :meth:`flatten`
-      method directly.  For example::
+      :class:`~email.generator.Generator` instance and use its
+      :meth:`~email.generator.Generator.flatten` method directly.  For example::
 
          from cStringIO import StringIO
@@ -134 +134 @@
       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`.
-
-      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
+      :mailheader:`Content-Type` header (the message will not be otherwise
+      modified).  Anything else will generate a :exc:`TypeError`.
+
+      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.
+
+      The message will be assumed to be of type :mimetype:`text/\*`, with the
+      payload either in unicode or encoded with *charset.input_charset*.
+      It will be encoded or converted to *charset.output_charset*
+      and transfer 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
@@ -266 +281 @@
       dashes are illegal in Python identifiers).  Normally, the parameter will
       be added as ``key="value"`` unless the value is ``None``, in which case
-      only the key will be added.
+      only the key will be added.  If the value contains non-ASCII characters,
+      it must be specified as a three tuple in the format
+      ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
+      charset to be used to encode the value, ``LANGUAGE`` can usually be set
+      to ``None`` or the empty string (see :RFC:`2231` for other possibilities),
+      and ``VALUE`` is the string value containing non-ASCII code points.
 
       Here's an example::
@@ -275 +295 @@
 
          Content-Disposition: attachment; filename="bud.gif"
+
+      An example with non-ASCII characters::
+
+         msg.add_header('Content-Disposition', 'attachment',
+                        filename=('iso-8859-1', '', 'Fußballer.ppt'))
+
+      Which produces ::
+
+         Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
 
 
@@ -380 +409 @@
       :func:`email.utils.collapse_rfc2231_value`, passing in the return value
       from :meth:`get_param`.  This will return a suitably decoded Unicode
-      string whn the value is a tuple, or the original string unquoted if it
+      string when the value is a tuple, or the original string unquoted if it
       isn't.  For example::
 
@@ -448 +477 @@
       :mailheader:`Content-Disposition` header of the message.  If the header
       does not have a ``filename`` parameter, this method falls back to looking
-      for the ``name`` parameter.  If neither is found, or the header is
-      missing, then *failobj* is returned.  The returned string will always be
-      unquoted as per :func:`email.utils.unquote`.
+      for the ``name`` parameter on the :mailheader:`Content-Type` header.  If
+      neither is found, or the header is missing, then *failobj* is returned.
+      The returned string will always be unquoted as per
+      :func:`email.utils.unquote`.
 
 
@@ -465 +495 @@
       Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
       *boundary*.  :meth:`set_boundary` will always quote *boundary* if
-      necessary.  A :exc:`HeaderParseError` is raised if the message object has
-      no :mailheader:`Content-Type` header.
+      necessary.  A :exc:`~email.errors.HeaderParseError` is raised if the
+      message object has no :mailheader:`Content-Type` header.
 
       Note that using this method is subtly different than deleting the old
@@ -560 +590 @@
       .. versionchanged:: 2.5
          You do not need to set the epilogue to the empty string in order for the
-         :class:`Generator` to print a newline at the end of the file.
+         :class:`~email.generator.Generator` to print a newline at the end of the
+         file.