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.
........

1 files changed, 59 insertions, 51 deletions

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.