Issue #18761: Improved cross-references in email documentation.

Doc/library/email.charset.rst

@@ -249,5 +249,5 @@ new entries to the global character set, alias, and codec registries:
 
    *charset* is the canonical name of a character set. *codecname* is the name of a
    Python codec, as appropriate for the second argument to the :func:`unicode`
-   built-in, or to the :meth:`encode` method of a Unicode string.
+   built-in, or to the :meth:`~unicode.encode` method of a Unicode string.
 

Doc/library/email.errors.rst

@@ -25,7 +25,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
 
    Raised under some error conditions when parsing the :rfc:`2822` headers of a
    message, this class is derived from :exc:`MessageParseError`. It can be raised
-   from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+   from the :meth:`Parser.parse <email.parser.Parser.parse>` or
+   :meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
 
    Situations where it can be raised include finding an envelope header after the
    first :rfc:`2822` header of the message, finding a continuation line before the
@@ -37,7 +38,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
 
    Raised under some error conditions when parsing the :rfc:`2822` headers of a
    message, this class is derived from :exc:`MessageParseError`. It can be raised
-   from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+   from the :meth:`Parser.parse <email.parser.Parser.parse>` or
+   :meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
 
    Situations where it can be raised include not being able to find the starting or
    terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
@@ -46,19 +48,20 @@ The following exception classes are defined in the :mod:`email.errors` module:
 
 .. exception:: MultipartConversionError()
 
-   Raised when a payload is added to a :class:`Message` object using
-   :meth:`add_payload`, but the payload is already a scalar and the message's
-   :mailheader:`Content-Type` main type is not either :mimetype:`multipart` or
-   missing.  :exc:`MultipartConversionError` multiply inherits from
-   :exc:`MessageError` and the built-in :exc:`TypeError`.
+   Raised when a payload is added to a :class:`~email.message.Message` object
+   using :meth:`add_payload`, but the payload is already a scalar and the
+   message's :mailheader:`Content-Type` main type is not either
+   :mimetype:`multipart` or missing.  :exc:`MultipartConversionError` multiply
+   inherits from :exc:`MessageError` and the built-in :exc:`TypeError`.
 
-   Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised
-   in practice.  However the exception may also be raised if the :meth:`attach`
+   Since :meth:`Message.add_payload` is deprecated, this exception is rarely
+   raised in practice.  However the exception may also be raised if the
+   :meth:`~email.message.Message.attach`
    method is called on an instance of a class derived from
    :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
    :class:`~email.mime.image.MIMEImage`).
 
-Here's the list of the defects that the :class:`~email.mime.parser.FeedParser`
+Here's the list of the defects that the :class:`~email.parser.FeedParser`
 can find while parsing messages.  Note that the defects are added to the message
 where the problem was found, so for example, if a message nested inside a
 :mimetype:`multipart/alternative` had a malformed header, that nested message
@@ -86,7 +89,7 @@ this class is *not* an exception!
   or was otherwise malformed.
 
 * :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
-  :mimetype:`multipart`, but no subparts were found.  Note that when a message has
-  this defect, its :meth:`is_multipart` method may return false even though its
-  content type claims to be :mimetype:`multipart`.
+  :mimetype:`multipart`, but no subparts were found.  Note that when a message
+  has this defect, its :meth:`~email.message.Message.is_multipart` method may
+  return false even though its content type claims to be :mimetype:`multipart`.
 

Doc/library/email.header.rst

@@ -103,7 +103,7 @@ Here is the :class:`Header` class description:
       not provoke a :exc:`UnicodeError` is used.
 
       Optional *errors* is passed through to any :func:`unicode` or
-      :func:`ustr.encode` call, and defaults to "strict".
+      :meth:`unicode.encode` call, and defaults to "strict".
 
 
    .. method:: encode([splitchars])

Doc/library/email.iterators.rst

@@ -6,8 +6,9 @@
 
 
 Iterating over a message object tree is fairly easy with the
-:meth:`Message.walk` method.  The :mod:`email.iterators` module provides some
-useful higher level iterations over message object trees.
+:meth:`Message.walk <email.message.Message.walk>` method.  The
+:mod:`email.iterators` module provides some useful higher level iterations over
+message object trees.
 
 
 .. function:: body_line_iterator(msg[, decode])
@@ -16,9 +17,11 @@ useful higher level iterations over message object trees.
    string payloads line-by-line.  It skips over all the subpart headers, and it
    skips over any subpart with a payload that isn't a Python string.  This is
    somewhat equivalent to reading the flat text representation of the message from
-   a file using :meth:`readline`, skipping over all the intervening headers.
+   a file using :meth:`~io.TextIOBase.readline`, skipping over all the
+   intervening headers.
 
-   Optional *decode* is passed through to :meth:`Message.get_payload`.
+   Optional *decode* is passed through to :meth:`Message.get_payload
+   <email.message.Message.get_payload>`.
 
 
 .. function:: typed_subpart_iterator(msg[, maintype[, subtype]])

Doc/library/email.message.rst

@@ -48,8 +48,8 @@ Here are the methods of the :class:`Message` class:
       Note that this method is provided as a convenience and may not always
       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
          from email.generator import Generator
@@ -494,8 +494,8 @@ Here are the methods of the :class:`Message` class:
 
       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
       :mailheader:`Content-Type` header and adding a new one with the new
@@ -589,7 +589,8 @@ Here are the methods of the :class:`Message` class:
 
       .. 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.
 
 
    .. attribute:: defects

Doc/library/email.mime.rst

@@ -35,7 +35,8 @@ Here are the classes:
    *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
    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
    (based on *_maintype*, *_subtype*, and *_params*), and a
@@ -50,8 +51,9 @@ Here are the classes:
 
    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.
 
    .. versionadded:: 2.2.2
@@ -76,7 +78,8 @@ Here are the classes:
 
    *_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
    the keyword arguments, or passed into the *_params* argument, which is a keyword
@@ -99,8 +102,10 @@ Here are the classes:
 
    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
    :mod:`email.encoders` module for a list of the built-in encoders.
@@ -127,8 +132,10 @@ Here are the classes:
 
    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
    :mod:`email.encoders` module for a list of the built-in encoders.
@@ -153,8 +160,10 @@ Here are the classes:
 
    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
    :mod:`email.encoders` module for a list of the built-in encoders.

Doc/library/email.parser.rst

@@ -7,7 +7,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.
 
 The :mod:`email` package provides a standard parser that understands most email
@@ -16,8 +17,9 @@ or a file object, and the parser will return to you the root
 :class:`~email.message.Message` instance of the object structure.  For simple,
 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
 :class:`Parser` API and the incremental :class:`FeedParser` API.  The classic
@@ -127,7 +129,8 @@ class.
 
       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`
       style headers and header continuation lines, optionally preceded by a
@@ -147,7 +150,7 @@ class.
 
       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
+      equivalent to wrapping *text* in a :class:`~StringIO.StringIO` instance first and
       calling :meth:`parse`.
 
       Optional *headersonly* is as with the :meth:`parse` method.
@@ -165,7 +168,7 @@ in the top-level :mod:`email` package namespace.
 
    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
       The *strict* flag was added.
@@ -175,7 +178,7 @@ in the top-level :mod:`email` package namespace.
 
    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
       The *strict* flag was added.
@@ -193,32 +196,35 @@ Here are some notes on the parsing semantics:
 
 * 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.
 

Doc/library/email.util.rst

@@ -41,8 +41,8 @@ There are several useful utilities provided in the :mod:`email.utils` module:
 
    This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
    *fieldvalues* is a sequence of header field values as might be returned by
-   :meth:`Message.get_all`.  Here's a simple example that gets all the recipients
-   of a message::
+   :meth:`Message.get_all <email.message.Message.get_all>`.  Here's a simple
+   example that gets all the recipients of a message::
 
       from email.utils import getaddresses
 
@@ -130,7 +130,8 @@ There are several useful utilities provided in the :mod:`email.utils` module:
 .. function:: collapse_rfc2231_value(value[, errors[, fallback_charset]])
 
    When a header parameter is encoded in :rfc:`2231` format,
-   :meth:`Message.get_param` may return a 3-tuple containing the character set,
+   :meth:`Message.get_param <email.message.Message.get_param>` may return a
+   3-tuple containing the character set,
    language, and value.  :func:`collapse_rfc2231_value` turns this into a unicode
    string.  Optional *errors* is passed to the *errors* argument of the built-in
    :func:`unicode` function; it defaults to ``replace``.  Optional
@@ -152,11 +153,12 @@ There are several useful utilities provided in the :mod:`email.utils` module:
 
 .. versionchanged:: 2.4
    The :func:`decode` function has been removed; use the
-   :meth:`Header.decode_header` method instead.
+   :meth:`Header.decode_header <email.header.Header.decode_header>` method
+   instead.
 
 .. versionchanged:: 2.4
-   The :func:`encode` function has been removed; use the :meth:`Header.encode`
-   method instead.
+   The :func:`encode` function has been removed; use the :meth:`Header.encode
+   <email.header.Header.encode>` method instead.
 
 .. rubric:: Footnotes