Merged revisions 71572 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r71572 | georg.brandl | 2009-04-13 15:13:25 +0200 (Mo, 13 Apr 2009) | 1 line

  #5745: more linking for identifiers in email docs.
........

8 files changed, 124 insertions, 111 deletions

diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst
index 01529a0..1244615 100644
--- a/Doc/library/email.charset.rst
+++ b/Doc/library/email.charset.rst
@@ -161,8 +161,8 @@ Import this class from the :mod:`email.charset` module.
       charset to the output charset automatically.  This is not useful for
       multibyte character sets, which have line length issues (multibyte
       characters must be split on a character, not a byte boundary); use the
-      higher-level :class:`Header` class to deal with these issues (see
-      :mod:`email.header`).  *convert* defaults to ``False``.
+      higher-level :class:`~email.header.Header` class to deal with these issues
+      (see :mod:`email.header`).  *convert* defaults to ``False``.
 
       The type of encoding (base64 or quoted-printable) will be based on the
       *header_encoding* attribute.
diff --git a/Doc/library/email.encoders.rst b/Doc/library/email.encoders.rst
index 28669c4..5421b9f 100644
--- a/Doc/library/email.encoders.rst
+++ b/Doc/library/email.encoders.rst
@@ -5,18 +5,18 @@
    :synopsis: Encoders for email message payloads.
 
 
-When creating :class:`Message` objects from scratch, you often need to encode
-the payloads for transport through compliant mail servers. This is especially
-true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages containing
-binary data.
+When creating :class:`~email.message.Message` objects from scratch, you often
+need to encode the payloads for transport through compliant mail servers. This
+is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages
+containing binary data.
 
 The :mod:`email` package provides some convenient encodings in its
 :mod:`encoders` module.  These encoders are actually used by the
-:class:`MIMEAudio` and :class:`MIMEImage` class constructors to provide default
-encodings.  All encoder functions take exactly one argument, the message object
-to encode.  They usually extract the payload, encode it, and reset the payload
-to this newly encoded value.  They should also set the
-:mailheader:`Content-Transfer-Encoding` header as appropriate.
+:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
+class constructors to provide default encodings.  All encoder functions take
+exactly one argument, the message object to encode.  They usually extract the
+payload, encode it, and reset the payload to this newly encoded value.  They
+should also set the :mailheader:`Content-Transfer-Encoding` header as appropriate.
 
 Here are the encoding functions provided:
 
diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst
index c68262f..2bd3ae4 100644
--- a/Doc/library/email.errors.rst
+++ b/Doc/library/email.errors.rst
@@ -17,8 +17,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
 
 .. exception:: MessageParseError()
 
-   This is the base class for exceptions thrown by the :class:`Parser` class.  It
-   is derived from :exc:`MessageError`.
+   This is the base class for exceptions thrown by the :class:`~email.parser.Parser`
+   class.  It is derived from :exc:`MessageError`.
 
 
 .. exception:: HeaderParseError()
@@ -55,11 +55,12 @@ The following exception classes are defined in the :mod:`email.errors` module:
    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`
    method is called on an instance of a class derived from
-   :class:`MIMENonMultipart` (e.g. :class:`MIMEImage`).
+   :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
+   :class:`~email.mime.image.MIMEImage`).
 
-Here's the list of the defects that the :class:`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
+Here's the list of the defects that the :class:`~email.mime.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
 object would have a defect, but the containing messages would not.
 
diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst
index 4e2ea2f..0f5788a 100644
--- a/Doc/library/email.generator.rst
+++ b/Doc/library/email.generator.rst
@@ -16,8 +16,8 @@ functionality of the bundled generator; you could write one from scratch
 yourself.  However the bundled generator knows how to generate most email in a
 standards-compliant way, should handle MIME and non-MIME email messages just
 fine, and is designed so that the transformation from flat text, to a message
-structure via the :class:`Parser` class, and back to flat text, is idempotent
-(the input is identical to the output).
+structure via the :class:`~email.parser.Parser` class, and back to flat text,
+is idempotent (the input is identical to the output).
 
 Here are the public methods of the :class:`Generator` class, imported from the
 :mod:`email.generator` module:
@@ -41,8 +41,8 @@ Here are the public methods of the :class:`Generator` class, imported from the
    Optional *maxheaderlen* specifies the longest length for a non-continued header.
    When a header line is longer than *maxheaderlen* (in characters, with tabs
    expanded to 8 spaces), the header will be split as defined in the
-   :mod:`email.header.Header` class.  Set to zero to disable header wrapping.  The
-   default is 78, as recommended (but not required) by :rfc:`2822`.
+   :class:`~email.header.Header` class.  Set to zero to disable header wrapping.
+   The default is 78, as recommended (but not required) by :rfc:`2822`.
 
    The other public :class:`Generator` methods are:
 
diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst
index 7ee4a2d..5da1d95 100644
--- a/Doc/library/email.header.rst
+++ b/Doc/library/email.header.rst
@@ -21,10 +21,10 @@ in its :mod:`email.header` and :mod:`email.charset` modules.
 
 If you want to include non-ASCII characters in your email headers, say in the
 :mailheader:`Subject` or :mailheader:`To` fields, you should use the
-:class:`Header` class and assign the field in the :class:`Message` object to an
-instance of :class:`Header` instead of using a string for the header value.
-Import the :class:`Header` class from the :mod:`email.header` module.  For
-example::
+:class:`Header` class and assign the field in the :class:`~email.message.Message`
+object to an instance of :class:`Header` instead of using a string for the header
+value.  Import the :class:`Header` class from the :mod:`email.header` module.
+For example::
 
    >>> from email.message import Message
    >>> from email.header import Header
@@ -39,9 +39,9 @@ example::
 Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
 character?  We did this by creating a :class:`Header` instance and passing in
 the character set that the byte string was encoded in.  When the subsequent
-:class:`Message` instance was flattened, the :mailheader:`Subject` field was
-properly :rfc:`2047` encoded.  MIME-aware mail readers would show this header
-using the embedded ISO-8859-1 character.
+:class:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
+field was properly :rfc:`2047` encoded.  MIME-aware mail readers would show this
+header using the embedded ISO-8859-1 character.
 
 Here is the :class:`Header` class description:
 
@@ -81,10 +81,11 @@ Here is the :class:`Header` class description:
 
       Append the string *s* to the MIME header.
 
-      Optional *charset*, if given, should be a :class:`Charset` instance (see
-      :mod:`email.charset`) or the name of a character set, which will be
-      converted to a :class:`Charset` instance.  A value of ``None`` (the
-      default) means that the *charset* given in the constructor is used.
+      Optional *charset*, if given, should be a :class:`~email.charset.Charset`
+      instance (see :mod:`email.charset`) or the name of a character set, which
+      will be converted to a :class:`~email.charset.Charset` instance.  A value
+      of ``None`` (the default) means that the *charset* given in the constructor
+      is used.
 
       *s* may be an instance of :class:`bytes` or :class:`str`.  If it is an
       instance of :class:`bytes`, then *charset* is the encoding of that byte
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index edeed16..7f70898 100644
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -45,8 +45,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:`Generator` instance and use its :meth:`flatten` method directly.
-      For example::
+      :class:`~email.generator.Generator` instance and use its :meth:`flatten`
+      method directly.  For example::
 
          from io import StringIO
          from email.generator import Generator
@@ -122,11 +122,12 @@ Here are the methods of the :class:`Message` class:
    .. method:: set_charset(charset)
 
       Set the character set of the payload to *charset*, which can either be a
-      :class:`Charset` instance (see :mod:`email.charset`), a string naming a
-      character set, or ``None``.  If it is a string, it will be converted to a
-      :class:`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`.
+      :class:`~email.charset.Charset` instance (see :mod:`email.charset`), a
+      string naming a character set, or ``None``.  If it is a string, it will
+      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*
@@ -137,8 +138,8 @@ Here are the methods of the :class:`Message` class:
 
    .. method:: get_charset()
 
-      Return the :class:`Charset` instance associated with the message's
-      payload.
+      Return the :class:`~email.charset.Charset` instance associated with the
+      message's payload.
 
    The following methods implement a mapping-like interface for accessing the
    message's :rfc:`2822` headers.  Note that there are some semantic differences
@@ -445,7 +446,7 @@ Here are the methods of the :class:`Message` class:
       that header has no ``charset`` parameter, *failobj* is returned.
 
       Note that this method differs from :meth:`get_charset` which returns the
-      :class:`Charset` instance for the default encoding of the message body.
+      :class:`~email.charset.Charset` instance for the default encoding of the message body.
 
 
    .. method:: get_charsets([failobj])
@@ -495,10 +496,11 @@ Here are the methods of the :class:`Message` class:
       text can become visible.
 
       The *preamble* attribute contains this leading extra-armor text for MIME
-      documents.  When the :class:`Parser` discovers some text after the headers
-      but before the first boundary string, it assigns this text to the
-      message's *preamble* attribute.  When the :class:`Generator` is writing
-      out the plain text representation of a MIME message, and it finds the
+      documents.  When the :class:`~email.parser.Parser` discovers some text
+      after the headers but before the first boundary string, it assigns this
+      text to the message's *preamble* attribute.  When the
+      :class:`~email.generator.Generator` is writing out the plain text
+      representation of a MIME message, and it finds the
       message has a *preamble* attribute, it will write this text in the area
       between the headers and the first boundary.  See :mod:`email.parser` and
       :mod:`email.generator` for details.
diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst
index 95407b0..0214d56 100644
--- a/Doc/library/email.mime.rst
+++ b/Doc/library/email.mime.rst
@@ -8,14 +8,15 @@
 Ordinarily, you get a message object structure by passing a file or some text to
 a parser, which parses the text and returns the root message object.  However
 you can also build a complete message structure from scratch, or even individual
-:class:`Message` objects by hand.  In fact, you can also take an existing
-structure and add new :class:`Message` objects, move them around, etc.  This
-makes a very convenient interface for slicing-and-dicing MIME messages.
+:class:`~email.message.Message` objects by hand.  In fact, you can also take an
+existing structure and add new :class:`~email.message.Message` objects, move them
+around, etc.  This makes a very convenient interface for slicing-and-dicing MIME
+messages.
 
-You can create a new object structure by creating :class:`Message` instances,
-adding attachments and all the appropriate headers manually.  For MIME messages
-though, the :mod:`email` package provides some convenient subclasses to make
-things easier.
+You can create a new object structure by creating :class:`~email.message.Message`
+instances, adding attachments and all the appropriate headers manually.  For MIME
+messages though, the :mod:`email` package provides some convenient subclasses to
+make things easier.
 
 Here are the classes:
 
@@ -25,10 +26,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.base`
 
-   This is the base class for all the MIME-specific subclasses of :class:`Message`.
-   Ordinarily you won't create instances specifically of :class:`MIMEBase`,
-   although you could.  :class:`MIMEBase` is provided primarily as a convenient
-   base class for more specific MIME-aware subclasses.
+   This is the base class for all the MIME-specific subclasses of
+   :class:`~email.message.Message`.  Ordinarily you won't create instances
+   specifically of :class:`MIMEBase`, although you could.  :class:`MIMEBase`
+   is provided primarily as a convenient base class for more specific
+   MIME-aware subclasses.
 
    *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
    or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
@@ -46,11 +48,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.nonmultipart`
 
-   A subclass of :class:`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` is called, a
-   :exc:`MultipartConversionError` exception is raised.
+   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`
+   is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
 
 
 .. currentmodule:: email.mime.multipart
@@ -59,12 +61,12 @@ Here are the classes:
 
    Module: :mod:`email.mime.multipart`
 
-   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
-   messages that are :mimetype:`multipart`.  Optional *_subtype* defaults to
-   :mimetype:`mixed`, but can be used to specify the subtype of the message.  A
-   :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype` will be
-   added to the message object.  A :mailheader:`MIME-Version` header will also be
-   added.
+   A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
+   class for MIME messages that are :mimetype:`multipart`.  Optional *_subtype*
+   defaults to :mimetype:`mixed`, but can be used to specify the subtype of the
+   message.  A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype`
+   will be added to the message object.  A :mailheader:`MIME-Version` header will
+   also be added.
 
    Optional *boundary* is the multipart boundary string.  When ``None`` (the
    default), the boundary is calculated when needed.
@@ -84,10 +86,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.application`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is
-   used to represent MIME message objects of major type :mimetype:`application`.
-   *_data* is a string containing the raw byte data.  Optional *_subtype* specifies
-   the MIME subtype and defaults to :mimetype:`octet-stream`.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEApplication` class is used to represent MIME message objects of
+   major type :mimetype:`application`.  *_data* is a string containing the raw
+   byte data.  Optional *_subtype* specifies the MIME subtype and defaults to
+   :mimetype:`octet-stream`.
 
    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
@@ -106,13 +109,14 @@ Here are the classes:
 
    Module: :mod:`email.mime.audio`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to
-   create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a
-   string containing the raw audio data.  If this data can be decoded by the
-   standard Python module :mod:`sndhdr`, then the subtype will be automatically
-   included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly
-   specify the audio subtype via the *_subtype* parameter.  If the minor type could
-   not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEAudio` class is used to create MIME message objects of major type
+   :mimetype:`audio`. *_audiodata* is a string containing the raw audio data.  If
+   this data can be decoded by the standard Python module :mod:`sndhdr`, then the
+   subtype will be automatically included in the :mailheader:`Content-Type` header.
+   Otherwise you can explicitly specify the audio subtype via the *_subtype*
+   parameter.  If the minor type could not be guessed and *_subtype* was not given,
+   then :exc:`TypeError` is raised.
 
    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,
@@ -131,13 +135,14 @@ Here are the classes:
 
    Module: :mod:`email.mime.image`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to
-   create MIME message objects of major type :mimetype:`image`. *_imagedata* is a
-   string containing the raw image data.  If this data can be decoded by the
-   standard Python module :mod:`imghdr`, then the subtype will be automatically
-   included in the :mailheader:`Content-Type` header.  Otherwise you can explicitly
-   specify the image subtype via the *_subtype* parameter.  If the minor type could
-   not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEImage` class is used to create MIME message objects of major type
+   :mimetype:`image`. *_imagedata* is a string containing the raw image data.  If
+   this data can be decoded by the standard Python module :mod:`imghdr`, then the
+   subtype will be automatically included in the :mailheader:`Content-Type` header.
+   Otherwise you can explicitly specify the image subtype via the *_subtype*
+   parameter.  If the minor type could not be guessed and *_subtype* was not given,
+   then :exc:`TypeError` is raised.
 
    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,
@@ -147,7 +152,8 @@ Here are the classes:
    object as necessary.  The default encoding is base64.  See the
    :mod:`email.encoders` module for a list of the built-in encoders.
 
-   *_params* are passed straight through to the :class:`MIMEBase` constructor.
+   *_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
+   constructor.
 
 
 .. currentmodule:: email.mime.message
@@ -156,10 +162,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.message`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used
-   to create MIME objects of main type :mimetype:`message`. *_msg* is used as the
-   payload, and must be an instance of class :class:`Message` (or a subclass
-   thereof), otherwise a :exc:`TypeError` is raised.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEMessage` class is used to create MIME objects of main type
+   :mimetype:`message`. *_msg* is used as the payload, and must be an instance
+   of class :class:`~email.message.Message` (or a subclass thereof), otherwise
+   a :exc:`TypeError` is raised.
 
    Optional *_subtype* sets the subtype of the message; it defaults to
    :mimetype:`rfc822`.
@@ -171,10 +178,11 @@ Here are the classes:
 
    Module: :mod:`email.mime.text`
 
-   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to
-   create MIME objects of major type :mimetype:`text`. *_text* is the string for
-   the payload.  *_subtype* is the minor type and defaults to :mimetype:`plain`.
-   *_charset* is the character set of the text and is passed as a parameter to the
-   :class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``.  No guessing
-   or encoding is performed on the text data.
+   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+   :class:`MIMEText` class is used to create MIME objects of major type
+   :mimetype:`text`. *_text* is the string for the payload.  *_subtype* is the
+   minor type and defaults to :mimetype:`plain`.  *_charset* is the character
+   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.
 
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index 43f0238..ec2e71b 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -6,18 +6,18 @@
 
 
 Message object structures can be created in one of two ways: they can be created
-from whole cloth by instantiating :class:`Message` objects and stringing them
-together via :meth:`attach` and :meth:`set_payload` calls, or they can be
-created by parsing a flat text representation of the email message.
+from whole cloth by instantiating :class:`~email.message.Message` objects and
+stringing them together via :meth:`attach` and :meth:`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
 document structures, including MIME documents.  You can pass the parser a string
-or a file object, and the parser will return to you the root :class:`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.
+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.
 
 There are actually two parser interfaces available for use, the classic
 :class:`Parser` API and the incremental :class:`FeedParser` API.  The classic
@@ -31,8 +31,8 @@ incrementally, and only returns the root object when you close the parser [#]_.
 Note that the parser can be extended in limited ways, and of course you can
 implement your own parser completely from scratch.  There is no magical
 connection between the :mod:`email` package's bundled parser and the
-:class:`Message` class, so your custom parser can create message object trees
-any way it finds necessary.
+:class:`~email.message.Message` class, so your custom parser can create message
+object trees any way it finds necessary.
 
 
 FeedParser API
@@ -101,8 +101,8 @@ class.
    The constructor for the :class:`Parser` class takes an optional argument
    *_class*.  This must be a callable factory (such as a function or a class), and
    it is used whenever a sub-message object needs to be created.  It defaults to
-   :class:`Message` (see :mod:`email.message`).  The factory will be called without
-   arguments.
+   :class:`~email.message.Message` (see :mod:`email.message`).  The factory will
+   be called without arguments.
 
    The optional *strict* flag is ignored.
 
@@ -179,7 +179,8 @@ Here are some notes on the parsing semantics:
 * 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:`Message` subparts.
+  :meth:`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