[Python-checkins] cpython (3.3): Issue #18761: Improved cross-references in email documentation.
serhiy.storchaka
python-checkins at python.org
Mon Aug 19 09:05:10 CEST 2013
http://hg.python.org/cpython/rev/7a1534dba050
changeset: 85259:7a1534dba050
branch: 3.3
parent: 85257:cfb510884a13
user: Serhiy Storchaka <storchaka at gmail.com>
date: Mon Aug 19 09:59:18 2013 +0300
summary:
Issue #18761: Improved cross-references in email documentation.
files:
Doc/library/email.charset.rst | 2 +-
Doc/library/email.errors.rst | 29 +-
Doc/library/email.headerregistry.rst | 15 +-
Doc/library/email.iterators.rst | 11 +-
Doc/library/email.message.rst | 11 +-
Doc/library/email.mime.rst | 29 +-
Doc/library/email.parser.rst | 56 ++-
Doc/library/email.policy.rst | 9 +-
Doc/library/email.rst | 183 ++++++++------
Doc/library/email.util.rst | 9 +-
10 files changed, 203 insertions(+), 151 deletions(-)
diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst
--- a/Doc/library/email.charset.rst
+++ b/Doc/library/email.charset.rst
@@ -234,5 +234,5 @@
*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
diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst
--- a/Doc/library/email.errors.rst
+++ b/Doc/library/email.errors.rst
@@ -25,7 +25,8 @@
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 @@
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 @@
.. 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 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
diff --git a/Doc/library/email.headerregistry.rst b/Doc/library/email.headerregistry.rst
--- a/Doc/library/email.headerregistry.rst
+++ b/Doc/library/email.headerregistry.rst
@@ -56,15 +56,16 @@
.. 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 @@
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 @@
.. 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 @@
.. class:: ContentDispositionHeader
- A :class:`ParameterizedMIMEHheader` class that handles the
+ A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Disposition` header.
.. attribute:: content-disposition
diff --git a/Doc/library/email.iterators.rst b/Doc/library/email.iterators.rst
--- a/Doc/library/email.iterators.rst
+++ b/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 @@
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)
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -55,8 +55,8 @@
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
@@ -476,8 +476,8 @@
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
@@ -573,7 +573,8 @@
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
diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst
--- a/Doc/library/email.mime.rst
+++ b/Doc/library/email.mime.rst
@@ -35,7 +35,8 @@
*_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 @@
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 @@
*_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 @@
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 @@
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 @@
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.
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
--- a/Doc/library/email.parser.rst
+++ b/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 @@
: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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
* 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.
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
--- a/Doc/library/email.policy.rst
+++ b/Doc/library/email.policy.rst
@@ -304,7 +304,7 @@
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.
@@ -448,10 +448,11 @@
.. 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.
diff --git a/Doc/library/email.rst b/Doc/library/email.rst
--- a/Doc/library/email.rst
+++ b/Doc/library/email.rst
@@ -147,14 +147,15 @@
*Note that the version 3 names will continue to work until Python 2.6*.
* The :mod:`email.mime.application` module was added, which contains the
- :class:`MIMEApplication` class.
+ :class:`~email.mime.application.MIMEApplication` class.
* Methods that were deprecated in version 3 have been removed. These include
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
* Fixes have been added for :rfc:`2231` support which can change some of the
- return types for :func:`Message.get_param` and friends. Under some
+ return types for :func:`Message.get_param <email.message.Message.get_param>`
+ and friends. Under some
circumstances, values which used to return a 3-tuple now return simple strings
(specifically, if all extended parameter segments were unencoded, there is no
language and charset designation expected, so the return type is now a simple
@@ -163,23 +164,24 @@
Here are the major differences between :mod:`email` version 3 and version 2:
-* The :class:`FeedParser` class was introduced, and the :class:`Parser` class
- was implemented in terms of the :class:`FeedParser`. All parsing therefore is
+* The :class:`~email.parser.FeedParser` class was introduced, and the
+ :class:`~email.parser.Parser` class was implemented in terms of the
+ :class:`~email.parser.FeedParser`. All parsing therefore is
non-strict, and parsing will make a best effort never to raise an exception.
Problems found while parsing messages are stored in the message's *defect*
attribute.
* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
have been removed. These include the *_encoder* argument to the
- :class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the
- :func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decode`
- and :func:`Utils.encode`.
+ :class:`~email.mime.text.MIMEText` constructor, the
+ :meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair`
+ function, and the functions :func:`Utils.decode` and :func:`Utils.encode`.
* New :exc:`DeprecationWarning`\ s have been added to:
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
- argument to the :class:`Parser` class. These are expected to be removed in
- future versions.
+ argument to the :class:`~email.parser.Parser` class. These are expected to
+ be removed in future versions.
* Support for Pythons earlier than 2.3 has been removed.
@@ -187,53 +189,61 @@
* The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
-* The pickle format for :class:`Message` instances has changed. Since this was
- never (and still isn't) formally defined, this isn't considered a backward
- incompatibility. However if your application pickles and unpickles
- :class:`Message` instances, be aware that in :mod:`email` version 2,
- :class:`Message` instances now have private variables *_charset* and
- *_default_type*.
+* The pickle format for :class:`~email.message.Message` instances has changed.
+ Since this was never (and still isn't) formally defined, this isn't
+ considered a backward incompatibility. However if your application pickles
+ and unpickles :class:`~email.message.Message` instances, be aware that in
+ :mod:`email` version 2, :class:`~email.message.Message` instances now have
+ private variables *_charset* and *_default_type*.
-* Several methods in the :class:`Message` class have been deprecated, or their
- signatures changed. Also, many new methods have been added. See the
- documentation for the :class:`Message` class for details. The changes should be
- completely backward compatible.
+* Several methods in the :class:`~email.message.Message` class have been
+ deprecated, or their signatures changed. Also, many new methods have been
+ added. See the documentation for the :class:`~email.message.Message` class
+ for details. The changes should be completely backward compatible.
* The object structure has changed in the face of :mimetype:`message/rfc822`
- content types. In :mod:`email` version 1, such a type would be represented by a
- scalar payload, i.e. the container message's :meth:`is_multipart` returned
- false, :meth:`get_payload` was not a list object, but a single :class:`Message`
- instance.
+ content types. In :mod:`email` version 1, such a type would be represented
+ by a scalar payload, i.e. the container message's
+ :meth:`~email.message.Message.is_multipart` returned false,
+ :meth:`~email.message.Message.get_payload` was not a list object, but a
+ single :class:`~email.message.Message` instance.
This structure was inconsistent with the rest of the package, so the object
representation for :mimetype:`message/rfc822` content types was changed. In
:mod:`email` version 2, the container *does* return ``True`` from
- :meth:`is_multipart`, and :meth:`get_payload` returns a list containing a single
- :class:`Message` item.
+ :meth:`~email.message.Message.is_multipart`, and
+ :meth:`~email.message.Message.get_payload` returns a list containing a single
+ :class:`~email.message.Message` item.
- Note that this is one place that backward compatibility could not be completely
- maintained. However, if you're already testing the return type of
- :meth:`get_payload`, you should be fine. You just need to make sure your code
- doesn't do a :meth:`set_payload` with a :class:`Message` instance on a container
- with a content type of :mimetype:`message/rfc822`.
+ Note that this is one place that backward compatibility could not be
+ completely maintained. However, if you're already testing the return type of
+ :meth:`~email.message.Message.get_payload`, you should be fine. You just need
+ to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
+ with a :class:`~email.message.Message` instance on a container with a content
+ type of :mimetype:`message/rfc822`.
-* The :class:`Parser` constructor's *strict* argument was added, and its
- :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The
- *strict* flag was also added to functions :func:`email.message_from_file` and
- :func:`email.message_from_string`.
+* The :class:`~email.parser.Parser` constructor's *strict* argument was added,
+ and its :meth:`~email.parser.Parser.parse` and
+ :meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument.
+ The *strict* flag was also added to functions :func:`email.message_from_file`
+ and :func:`email.message_from_string`.
-* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten`
- instead. The :class:`Generator` class has also grown the :meth:`clone` method.
+* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten
+ <email.generator.Generator.flatten>` instead. The
+ :class:`~email.generator.Generator` class has also grown the
+ :meth:`~email.generator.Generator.clone` method.
-* The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was
- added.
+* The :class:`~email.generator.DecodedGenerator` class in the
+ :mod:`email.generator` module was added.
-* The intermediate base classes :class:`MIMENonMultipart` and
- :class:`MIMEMultipart` have been added, and interposed in the class hierarchy
- for most of the other MIME-related derived classes.
+* The intermediate base classes
+ :class:`~email.mime.nonmultipart.MIMENonMultipart` and
+ :class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed
+ in the class hierarchy for most of the other MIME-related derived classes.
-* The *_encoder* argument to the :class:`MIMEText` constructor has been
- deprecated. Encoding now happens implicitly based on the *_charset* argument.
+* The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor
+ has been deprecated. Encoding now happens implicitly based on the
+ *_charset* argument.
* The following functions in the :mod:`email.Utils` module have been deprecated:
:func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
@@ -266,17 +276,22 @@
* :func:`messageFromFile` has been renamed to :func:`message_from_file`.
-The :class:`Message` class has the following differences:
+The :class:`~email.message.Message` class has the following differences:
-* The method :meth:`asString` was renamed to :meth:`as_string`.
+* The method :meth:`asString` was renamed to
+ :meth:`~email.message.Message.as_string`.
-* The method :meth:`ismultipart` was renamed to :meth:`is_multipart`.
+* The method :meth:`ismultipart` was renamed to
+ :meth:`~email.message.Message.is_multipart`.
-* The :meth:`get_payload` method has grown a *decode* optional argument.
+* The :meth:`~email.message.Message.get_payload` method has grown a *decode*
+ optional argument.
-* The method :meth:`getall` was renamed to :meth:`get_all`.
+* The method :meth:`getall` was renamed to
+ :meth:`~email.message.Message.get_all`.
-* The method :meth:`addheader` was renamed to :meth:`add_header`.
+* The method :meth:`addheader` was renamed to
+ :meth:`~email.message.Message.add_header`.
* The method :meth:`gettype` was renamed to :meth:`get_type`.
@@ -284,48 +299,57 @@
* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
-* The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas
- :meth:`getparams` returned a list of strings, :meth:`get_params` returns a list
- of 2-tuples, effectively the key/value pairs of the parameters, split on the
- ``'='`` sign.
+* The method :meth:`getparams` was renamed to
+ :meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
+ returned a list of strings, :meth:`~email.message.Message.get_params` returns
+ a list of 2-tuples, effectively the key/value pairs of the parameters, split
+ on the ``'='`` sign.
-* The method :meth:`getparam` was renamed to :meth:`get_param`.
+* The method :meth:`getparam` was renamed to
+ :meth:`~email.message.Message.get_param`.
-* The method :meth:`getcharsets` was renamed to :meth:`get_charsets`.
+* The method :meth:`getcharsets` was renamed to
+ :meth:`~email.message.Message.get_charsets`.
-* The method :meth:`getfilename` was renamed to :meth:`get_filename`.
+* The method :meth:`getfilename` was renamed to
+ :meth:`~email.message.Message.get_filename`.
-* The method :meth:`getboundary` was renamed to :meth:`get_boundary`.
+* The method :meth:`getboundary` was renamed to
+ :meth:`~email.message.Message.get_boundary`.
-* The method :meth:`setboundary` was renamed to :meth:`set_boundary`.
+* The method :meth:`setboundary` was renamed to
+ :meth:`~email.message.Message.set_boundary`.
* The method :meth:`getdecodedpayload` was removed. To get similar
- functionality, pass the value 1 to the *decode* flag of the get_payload()
- method.
+ functionality, pass the value 1 to the *decode* flag of the
+ :meth:`~email.message.Message.get_payload` method.
* The method :meth:`getpayloadastext` was removed. Similar functionality is
- supported by the :class:`DecodedGenerator` class in the :mod:`email.generator`
+ supported by the :class:`~email.generator.DecodedGenerator` class in the
+ :mod:`email.generator` module.
+
+* The method :meth:`getbodyastext` was removed. You can get similar
+ functionality by creating an iterator with
+ :func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators`
module.
-* The method :meth:`getbodyastext` was removed. You can get similar
- functionality by creating an iterator with :func:`typed_subpart_iterator` in the
- :mod:`email.iterators` module.
+The :class:`~email.parser.Parser` class has no differences in its public
+interface. It does have some additional smarts to recognize
+:mimetype:`message/delivery-status` type messages, which it represents as a
+:class:`~email.message.Message` instance containing separate
+:class:`~email.message.Message` subparts for each header block in the delivery
+status notification [#]_.
-The :class:`Parser` class has no differences in its public interface. It does
-have some additional smarts to recognize :mimetype:`message/delivery-status`
-type messages, which it represents as a :class:`Message` instance containing
-separate :class:`Message` subparts for each header block in the delivery status
-notification [#]_.
-
-The :class:`Generator` class has no differences in its public interface. There
-is a new class in the :mod:`email.generator` module though, called
-:class:`DecodedGenerator` which provides most of the functionality previously
-available in the :meth:`Message.getpayloadastext` method.
+The :class:`~email.generator.Generator` class has no differences in its public
+interface. There is a new class in the :mod:`email.generator` module though,
+called :class:`~email.generator.DecodedGenerator` which provides most of the
+functionality previously available in the :meth:`Message.getpayloadastext`
+method.
The following modules and classes have been changed:
-* The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have
- changed to *_maintype* and *_subtype* respectively.
+* The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major*
+ and *_minor* have changed to *_maintype* and *_subtype* respectively.
* The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
argument has been renamed to *_subtype*.
@@ -338,7 +362,8 @@
but that clashed with the Python standard library module :mod:`rfc822` on some
case-insensitive file systems.
- Also, the :class:`MIMEMessage` class now represents any kind of MIME message
+ Also, the :class:`~email.mime.message.MIMEMessage` class now represents any
+ kind of MIME message
with main type :mimetype:`message`. It takes an optional argument *_subtype*
which is used to set the MIME subtype. *_subtype* defaults to
:mimetype:`rfc822`.
@@ -348,8 +373,8 @@
:mod:`email.utils` module.
The ``MsgReader`` class/module has been removed. Its functionality is most
-closely supported in the :func:`body_line_iterator` function in the
-:mod:`email.iterators` module.
+closely supported in the :func:`~email.iterators.body_line_iterator` function
+in the :mod:`email.iterators` module.
.. rubric:: Footnotes
diff --git a/Doc/library/email.util.rst b/Doc/library/email.util.rst
--- a/Doc/library/email.util.rst
+++ b/Doc/library/email.util.rst
@@ -49,8 +49,8 @@
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 @@
.. 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'``.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list