[Python-checkins] r72028 - in python/branches/py3k: Doc/library/email.charset.rst Doc/library/email.encoders.rst Doc/library/email.errors.rst Doc/library/email.generator.rst Doc/library/email.header.rst Doc/library/email.message.rst Doc/library/email.mime.rst Doc/library/email.parser.rst
georg.brandl
python-checkins at python.org
Mon Apr 27 18:46:17 CEST 2009
Author: georg.brandl
Date: Mon Apr 27 18:46:17 2009
New Revision: 72028
Log:
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.
........
Modified:
python/branches/py3k/ (props changed)
python/branches/py3k/Doc/library/email.charset.rst
python/branches/py3k/Doc/library/email.encoders.rst
python/branches/py3k/Doc/library/email.errors.rst
python/branches/py3k/Doc/library/email.generator.rst
python/branches/py3k/Doc/library/email.header.rst
python/branches/py3k/Doc/library/email.message.rst
python/branches/py3k/Doc/library/email.mime.rst
python/branches/py3k/Doc/library/email.parser.rst
Modified: python/branches/py3k/Doc/library/email.charset.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.charset.rst (original)
+++ python/branches/py3k/Doc/library/email.charset.rst Mon Apr 27 18:46:17 2009
@@ -161,8 +161,8 @@
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.
Modified: python/branches/py3k/Doc/library/email.encoders.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.encoders.rst (original)
+++ python/branches/py3k/Doc/library/email.encoders.rst Mon Apr 27 18:46:17 2009
@@ -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:
Modified: python/branches/py3k/Doc/library/email.errors.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.errors.rst (original)
+++ python/branches/py3k/Doc/library/email.errors.rst Mon Apr 27 18:46:17 2009
@@ -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,11 +55,12 @@
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.
Modified: python/branches/py3k/Doc/library/email.generator.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.generator.rst (original)
+++ python/branches/py3k/Doc/library/email.generator.rst Mon Apr 27 18:46:17 2009
@@ -16,8 +16,8 @@
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 @@
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:
Modified: python/branches/py3k/Doc/library/email.header.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.header.rst (original)
+++ python/branches/py3k/Doc/library/email.header.rst Mon Apr 27 18:46:17 2009
@@ -21,10 +21,10 @@
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 @@
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 @@
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
Modified: python/branches/py3k/Doc/library/email.message.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.message.rst (original)
+++ python/branches/py3k/Doc/library/email.message.rst Mon Apr 27 18:46:17 2009
@@ -45,8 +45,8 @@
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 @@
.. 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 @@
.. 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 @@
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 @@
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.
Modified: python/branches/py3k/Doc/library/email.mime.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.mime.rst (original)
+++ python/branches/py3k/Doc/library/email.mime.rst Mon Apr 27 18:46:17 2009
@@ -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.
-
-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.
+: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:`~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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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.
Modified: python/branches/py3k/Doc/library/email.parser.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.parser.rst (original)
+++ python/branches/py3k/Doc/library/email.parser.rst Mon Apr 27 18:46:17 2009
@@ -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 @@
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 @@
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 @@
* 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
More information about the Python-checkins
mailing list