Index: Doc/library/email.charset.rst =================================================================== --- Doc/library/email.charset.rst (revision 71502) +++ Doc/library/email.charset.rst (working copy) @@ -163,7 +163,7 @@ 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 + 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 Index: Doc/library/email.encoders.rst =================================================================== --- Doc/library/email.encoders.rst (revision 71502) +++ Doc/library/email.encoders.rst (working copy) @@ -5,14 +5,14 @@ :synopsis: Encoders for email message payloads. -When creating :class:`Message` objects from scratch, you often need to encode +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 +: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 Index: Doc/library/email.errors.rst =================================================================== --- Doc/library/email.errors.rst (revision 71502) +++ Doc/library/email.errors.rst (working copy) @@ -17,8 +17,8 @@ .. 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,9 +55,9 @@ 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 +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 Index: Doc/library/email.generator.rst =================================================================== --- Doc/library/email.generator.rst (revision 71502) +++ Doc/library/email.generator.rst (working copy) @@ -16,7 +16,7 @@ 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 +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 @@ -41,7 +41,7 @@ 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 + :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: Index: Doc/library/email.header.rst =================================================================== --- Doc/library/email.header.rst (revision 71502) +++ Doc/library/email.header.rst (working copy) @@ -21,7 +21,7 @@ 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 +: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:: @@ -39,7 +39,7 @@ 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 +: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. @@ -84,9 +84,9 @@ Append the string *s* to the MIME header. - Optional *charset*, if given, should be a :class:`Charset` instance (see + 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:`Charset` instance. A value of ``None`` (the + 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 a byte string or a Unicode string. If it is a byte string Index: Doc/library/email.message.rst =================================================================== --- Doc/library/email.message.rst (revision 71555) +++ Doc/library/email.message.rst (working copy) @@ -45,7 +45,7 @@ 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. + :class:`~email.generator.Generator` instance and use its :meth:`flatten` method directly. For example:: from cStringIO import StringIO @@ -126,9 +126,9 @@ .. 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 + :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:`Charset` instance. If *charset* is ``None``, the ``charset`` + :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`. @@ -144,7 +144,7 @@ .. method:: get_charset() - Return the :class:`Charset` instance associated with the message's + Return the :class:`~email.charset.Charset` instance associated with the message's payload. .. versionadded:: 2.2.2 @@ -478,7 +478,7 @@ 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. .. versionadded:: 2.2.2 @@ -534,9 +534,9 @@ 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 + 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:`Generator` is writing + 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 Index: Doc/library/email.mime.rst =================================================================== --- Doc/library/email.mime.rst (revision 71502) +++ Doc/library/email.mime.rst (working copy) @@ -8,11 +8,11 @@ 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 +: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, +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. @@ -25,7 +25,7 @@ Module: :mod:`email.mime.base` - This is the base class for all the MIME-specific subclasses of :class:`Message`. + 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. @@ -46,11 +46,11 @@ Module: :mod:`email.mime.nonmultipart` - A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME + 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:`MultipartConversionError` exception is raised. + :exc:`~email.errors.MultipartConversionError` exception is raised. .. versionadded:: 2.2.2 @@ -61,7 +61,7 @@ Module: :mod:`email.mime.multipart` - A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME + 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 @@ -88,7 +88,7 @@ Module: :mod:`email.mime.application` - A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is + 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`. @@ -112,7 +112,7 @@ Module: :mod:`email.mime.audio` - A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to + 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 @@ -137,7 +137,7 @@ Module: :mod:`email.mime.image` - A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to + 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 @@ -153,7 +153,7 @@ 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 @@ -162,9 +162,9 @@ Module: :mod:`email.mime.message` - A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used + 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:`Message` (or a subclass + 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 @@ -177,11 +177,11 @@ Module: :mod:`email.mime.text` - A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to + 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:`MIMENonMultipart` constructor; it defaults to ``us-ascii``. No guessing + :class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults to ``us-ascii``. No guessing or encoding is performed on the text data. .. versionchanged:: 2.4 Index: Doc/library/email.parser.rst =================================================================== --- Doc/library/email.parser.rst (revision 71502) +++ Doc/library/email.parser.rst (working copy) @@ -6,13 +6,13 @@ 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 +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` +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 @@ -31,7 +31,7 @@ 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 +:class:`~email.message.Message` class, so your custom parser can create message object trees any way it finds necessary. @@ -103,7 +103,7 @@ 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 + :class:`~email.message.Message` (see :mod:`email.message`). The factory will be called without arguments. The optional *strict* flag is ignored. @@ -199,7 +199,7 @@ * 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