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

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

@@ -1 @@
-:mod:`email`: Parsing email messages
-------------------------------------
+:mod:`email.parser`: Parsing email messages
+-------------------------------------------
 
 .. module:: email.parser
@@ -8 +8 @@
 Message object structures can be created in one of two ways: they can be created
 from whole cloth by instantiating :class:`~email.message.Message` objects and
-stringing them together via :meth:`attach` and :meth:`set_payload` calls, or they
+stringing them together via :meth:`~email.message.Message.attach` and
+:meth:`~email.message.Message.set_payload` calls, or they
 can be created by parsing a flat text representation of the email message.
 
@@ -17 +18 @@
 non-MIME messages the payload of this root object will likely be a string
 containing the text of the message.  For MIME messages, the root object will
-return ``True`` from its :meth:`is_multipart` method, and the subparts can be
-accessed via the :meth:`get_payload` and :meth:`walk` methods.
+return ``True`` from its :meth:`~email.message.Message.is_multipart` method, and
+the subparts can be accessed via the :meth:`~email.message.Message.get_payload`
+and :meth:`~email.message.Message.walk` methods.
 
 There are actually two parser interfaces available for use, the classic
@@ -128 +130 @@
       Read all the data from the file-like object *fp*, parse the resulting
       text, and return the root message object.  *fp* must support both the
-      :meth:`readline` and the :meth:`read` methods on file-like objects.
+      :meth:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.read`
+      methods on file-like objects.
 
       The text contained in *fp* must be formatted as a block of :rfc:`2822`
@@ -136 +139 @@
       message (which may contain MIME-encoded subparts).
 
-      Optional *headersonly* is as with the :meth:`parse` method.
-
-      .. versionchanged:: 2.2.2
-         The *headersonly* flag was added.
-
-
-   .. method:: parsestr(text[, headersonly])
-
-      Similar to the :meth:`parse` method, except it takes a string object
-      instead of a file-like object.  Calling this method on a string is exactly
-      equivalent to wrapping *text* in a :class:`StringIO` instance first and
-      calling :meth:`parse`.
-
       Optional *headersonly* is a flag specifying whether to stop parsing after
       reading the headers or not.  The default is ``False``, meaning it parses
@@ -156 +146 @@
          The *headersonly* flag was added.
 
+
+   .. method:: parsestr(text[, headersonly])
+
+      Similar to the :meth:`parse` method, except it takes a string object
+      instead of a file-like object.  Calling this method on a string is exactly
+      equivalent to wrapping *text* in a :class:`~StringIO.StringIO` instance first and
+      calling :meth:`parse`.
+
+      Optional *headersonly* is as with the :meth:`parse` method.
+
+      .. versionchanged:: 2.2.2
+         The *headersonly* flag was added.
+
 Since creating a message object structure from a string or a file object is such
 a common task, two functions are provided as a convenience.  They are available
@@ -166 +169 @@
    Return a message object structure from a string.  This is exactly equivalent to
    ``Parser().parsestr(s)``.  Optional *_class* and *strict* are interpreted as
-   with the :class:`Parser` class constructor.
+   with the :class:`~email.parser.Parser` class constructor.
 
    .. versionchanged:: 2.2.2
@@ -176 +179 @@
    Return a message object structure tree from an open file object.  This is
    exactly equivalent to ``Parser().parse(fp)``.  Optional *_class* and *strict*
-   are interpreted as with the :class:`Parser` class constructor.
+   are interpreted as with the :class:`~email.parser.Parser` class constructor.
 
    .. versionchanged:: 2.2.2
@@ -194 +197 @@
 * Most non-\ :mimetype:`multipart` type messages are parsed as a single message
   object with a string payload.  These objects will return ``False`` for
-  :meth:`is_multipart`.  Their :meth:`get_payload` method will return a string
-  object.
+  :meth:`~email.message.Message.is_multipart`.  Their
+  :meth:`~email.message.Message.get_payload` method will return a string object.
 
 * All :mimetype:`multipart` type messages will be parsed as a container message
   object with a list of sub-message objects for their payload.  The outer
-  container message will return ``True`` for :meth:`is_multipart` and their
-  :meth:`get_payload` method will return the list of :class:`~email.message.Message`
-  subparts.
+  container message will return ``True`` for
+  :meth:`~email.message.Message.is_multipart` and their
+  :meth:`~email.message.Message.get_payload` method will return the list of
+  :class:`~email.message.Message` subparts.
 
 * Most messages with a content type of :mimetype:`message/\*` (e.g.
   :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
   parsed as container object containing a list payload of length 1.  Their
-  :meth:`is_multipart` method will return ``True``.  The single element in the
-  list payload will be a sub-message object.
+  :meth:`~email.message.Message.is_multipart` method will return ``True``.
+  The single element in the list payload will be a sub-message object.
 
 * Some non-standards compliant messages may not be internally consistent about
   their :mimetype:`multipart`\ -edness.  Such messages may have a
   :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
-  :meth:`is_multipart` method may return ``False``.  If such messages were parsed
-  with the :class:`FeedParser`, they will have an instance of the
-  :class:`MultipartInvariantViolationDefect` class in their *defects* attribute
-  list.  See :mod:`email.errors` for details.
+  :meth:`~email.message.Message.is_multipart` method may return ``False``.
+  If such messages were parsed with the :class:`~email.parser.FeedParser`,
+  they will have an instance of the
+  :class:`~email.errors.MultipartInvariantViolationDefect` class in their
+  *defects* attribute list.  See :mod:`email.errors` for details.
 
 .. rubric:: Footnotes
 
 .. [#] As of email package version 3.0, introduced in Python 2.4, the classic
-   :class:`Parser` was re-implemented in terms of the :class:`FeedParser`, so the
-   semantics and results are identical between the two parsers.
-
+   :class:`~email.parser.Parser` was re-implemented in terms of the
+   :class:`~email.parser.FeedParser`, so the semantics and results are
+   identical between the two parsers.
+