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

Doc/library/email.charset.rst

@@ -234,5 +234,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 :class:`str`'s
-   :func:`decode` method
+   :meth:`~str.encode` method
 

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
@@ -97,9 +100,9 @@ this class is *not* an exception!
      This defect has not been used for several Python versions.
 
 * :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`.
 
 * :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64
   enocded bytes, the padding was not correct.  Enough padding is added to

Doc/library/email.headerregistry.rst

@@ -56,15 +56,16 @@ headers.
    .. attribute:: name
 
       The name of the header (the portion of the field before the ':').  This
-      is exactly the value passed in the :attr:`~EmailPolicy.header_factory`
-      call for *name*; that is, case is preserved.
+      is exactly the value passed in the
+      :attr:`~email.policy.EmailPolicy.header_factory` call for *name*; that
+      is, case is preserved.
 
 
    .. attribute:: defects
 
       A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any
       RFC compliance problems found during parsing.  The email package tries to
-      be complete about detecting compliance issues.  See the :mod:`errors`
+      be complete about detecting compliance issues.  See the :mod:`~email.errors`
       module for a discussion of the types of defects that may be reported.
 
 
@@ -230,8 +231,8 @@ headers.
 
       The single address encoded by the header value.  If the header value
       actually contains more than one address (which would be a violation of
-      the RFC under the default :mod:`policy`), accessing this attribute will
-      result in a :exc:`ValueError`.
+      the RFC under the default :mod:`~email.policy`), accessing this attribute
+      will result in a :exc:`ValueError`.
 
 
 Many of the above classes also have a ``Unique`` variant (for example,
@@ -275,7 +276,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
 
 .. class:: ContentTypeHeader
 
-    A :class:`ParameterizedMIMEHheader` class that handles the
+    A :class:`ParameterizedMIMEHeader` class that handles the
     :mailheader:`Content-Type` header.
 
     .. attribute:: content_type
@@ -289,7 +290,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
 
 .. class:: ContentDispositionHeader
 
-    A :class:`ParameterizedMIMEHheader` class that handles the
+    A :class:`ParameterizedMIMEHeader` class that handles the
     :mailheader:`Content-Disposition` header.
 
     .. attribute:: content-disposition

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=False)
@@ -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='text', subtype=None)

Doc/library/email.message.rst

@@ -62,8 +62,8 @@ Here are the methods of the :class:`Message` class:
       format the message the way you want.  For example, by default it does
       not do the mangling of lines that begin with ``From`` that is
       required by the unix mbox format.  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 io import StringIO
          from email.generator import Generator
@@ -105,7 +105,8 @@ Here are the methods of the :class:`Message` class:
       not do the mangling of lines that begin with ``From`` that is
       required by the unix mbox format.  For more flexibility, instantiate a
       :class:`~email.generator.BytesGenerator` instance and use its
-      :meth:`flatten` method directly.  For example::
+      :meth:`~email.generator.BytesGenerator.flatten` method directly.
+      For example::
 
          from io import BytesIO
          from email.generator import BytesGenerator
@@ -530,8 +531,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
@@ -627,7 +628,8 @@ Here are the methods of the :class:`Message` class:
       the end of the message.
 
       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.
 
 
@@ -74,7 +76,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
@@ -95,8 +98,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.
@@ -121,8 +126,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.
@@ -147,8 +154,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
@@ -134,7 +136,8 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
 
       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
@@ -173,8 +176,8 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
 
       Read all the data from the binary file-like object *fp*, parse the
       resulting bytes, and return the message object.  *fp* must support
-      both the :meth:`readline` and the :meth:`read` methods on file-like
-      objects.
+      both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
+      methods on file-like objects.
 
       The bytes contained in *fp* must be formatted as a block of :rfc:`2822`
       style headers and header continuation lines, optionally preceded by a
@@ -210,7 +213,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)``.  *_class* and *policy* are interpreted as
-   with the :class:`Parser` class constructor.
+   with the :class:`~email.parser.Parser` class constructor.
 
    .. versionchanged:: 3.3
       Removed the *strict* argument.  Added the *policy* keyword.
@@ -220,7 +223,8 @@ in the top-level :mod:`email` package namespace.
 
    Return a message object structure from a byte string.  This is exactly
    equivalent to ``BytesParser().parsebytes(s)``.  Optional *_class* and
-   *strict* are interpreted as with the :class:`Parser` class constructor.
+   *strict* are interpreted as with the :class:`~email.parser.Parser` class
+   constructor.
 
    .. versionadded:: 3.2
    .. versionchanged:: 3.3
@@ -231,7 +235,8 @@ in the top-level :mod:`email` package namespace.
 
    Return a message object structure tree from an open :term:`file object`.
    This is exactly equivalent to ``Parser().parse(fp)``.  *_class*
-   and *policy* are interpreted as with the :class:`Parser` class constructor.
+   and *policy* are interpreted as with the :class:`~email.parser.Parser` class
+   constructor.
 
    .. versionchanged::
       Removed the *strict* argument.  Added the *policy* keyword.
@@ -241,8 +246,8 @@ in the top-level :mod:`email` package namespace.
 
    Return a message object structure tree from an open binary :term:`file
    object`.  This is exactly equivalent to ``BytesParser().parse(fp)``.
-   *_class* and *policy* are interpreted as with the :class:`Parser`
-   class constructor.
+   *_class* and *policy* are interpreted as with the
+   :class:`~email.parser.Parser` class constructor.
 
    .. versionadded:: 3.2
    .. versionchanged:: 3.3
@@ -261,32 +266,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.policy.rst

@@ -315,7 +315,7 @@ added matters.  To illustrate::
 
    This concrete :class:`Policy` is the backward compatibility policy.  It
    replicates the behavior of the email package in Python 3.2.  The
-   :mod:`policy` module also defines an instance of this class,
+   :mod:`~email.policy` module also defines an instance of this class,
    :const:`compat32`, that is used as the default policy.  Thus the default
    behavior of the email package is to maintain compatibility with Python 3.2.
 
@@ -459,10 +459,11 @@ added matters.  To illustrate::
 
    .. method:: fold_binary(name, value)
 
-      The same as :meth:`fold` if :attr:`cte_type` is ``7bit``, except that
-      the returned value is bytes.
+      The same as :meth:`fold` if :attr:`~Policy.cte_type` is ``7bit``, except
+      that the returned value is bytes.
 
-      If :attr:`cte_type` is ``8bit``, non-ASCII binary data is converted back
+      If :attr:`~Policy.cte_type` is ``8bit``, non-ASCII binary data is
+      converted back
       into bytes.  Headers with binary data are not refolded, regardless of the
       ``refold_header`` setting, since there is no way to know whether the
       binary data consists of single byte characters or multibyte characters.

Doc/library/email.util.rst

@@ -49,8 +49,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
 
@@ -187,10 +187,11 @@ There are several useful utilities provided in the :mod:`email.utils` module:
 .. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')
 
    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 :class:`str`'s
-   :func:`encode` method; it defaults to ``'replace'``.  Optional
+   :func:`~str.encode` method; it defaults to ``'replace'``.  Optional
    *fallback_charset* specifies the character set to use if the one in the
    :rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``.