mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-12 11:46:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Issue #18761: Improved cross-references in email documentation.

Browse source
This commit is contained in:
Serhiy Storchaka 2013-08-19 10:03:11 +03:00
commit 319f3a10f9
10 changed files with 204 additions and 151 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Doc/library/email.charset.rst
View file

@ -234,5 +234,5 @@ new entries to the global character set, alias, and codec registries:
*charset* is the canonical name of a character set. *codecname* is the name of a *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 Python codec, as appropriate for the second argument to the :class:`str`'s
:func:`decode` method :meth:`~str.encode` method

29
Doc/library/email.errors.rst
View file

@ -25,7 +25,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
Raised under some error conditions when parsing the :rfc:`2822` headers of a 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 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 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 first :rfc:`2822` header of the message, finding a continuation line before the
@ -37,7 +38,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
Raised under some error conditions when parsing the :rfc:`2822` headers of a 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 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 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 terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
@ -46,19 +48,20 @@ The following exception classes are defined in the :mod:`email.errors` module:
.. exception:: MultipartConversionError() .. exception:: MultipartConversionError()
Raised when a payload is added to a :class:`Message` object using Raised when a payload is added to a :class:`~email.message.Message` object
:meth:`add_payload`, but the payload is already a scalar and the message's using :meth:`add_payload`, but the payload is already a scalar and the
:mailheader:`Content-Type` main type is not either :mimetype:`multipart` or message's :mailheader:`Content-Type` main type is not either
missing. :exc:`MultipartConversionError` multiply inherits from :mimetype:`multipart` or missing. :exc:`MultipartConversionError` multiply
:exc:`MessageError` and the built-in :exc:`TypeError`. inherits from :exc:`MessageError` and the built-in :exc:`TypeError`.
Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised Since :meth:`Message.add_payload` is deprecated, this exception is rarely
in practice. However the exception may also be raised if the :meth:`attach` 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 method is called on an instance of a class derived from
:class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g. :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
:class:`~email.mime.image.MIMEImage`). :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 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 where the problem was found, so for example, if a message nested inside a
:mimetype:`multipart/alternative` had a malformed header, that nested message :mimetype:`multipart/alternative` had a malformed header, that nested message
@ -97,9 +100,9 @@ this class is *not* an exception!
This defect has not been used for several Python versions. This defect has not been used for several Python versions.
* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a * :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
:mimetype:`multipart`, but no subparts were found. Note that when a message has :mimetype:`multipart`, but no subparts were found. Note that when a message
this defect, its :meth:`is_multipart` method may return false even though its has this defect, its :meth:`~email.message.Message.is_multipart` method may
content type claims to be :mimetype:`multipart`. return false even though its content type claims to be :mimetype:`multipart`.
* :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64 * :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64
enocded bytes, the padding was not correct. Enough padding is added to enocded bytes, the padding was not correct. Enough padding is added to

15
Doc/library/email.headerregistry.rst
View file

@ -56,15 +56,16 @@ headers.
.. attribute:: name .. attribute:: name
The name of the header (the portion of the field before the ':'). This The name of the header (the portion of the field before the ':'). This
is exactly the value passed in the :attr:`~EmailPolicy.header_factory` is exactly the value passed in the
call for *name*; that is, case is preserved. :attr:`~email.policy.EmailPolicy.header_factory` call for *name*; that
is, case is preserved.
.. attribute:: defects .. attribute:: defects
A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any
RFC compliance problems found during parsing. The email package tries to 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. module for a discussion of the types of defects that may be reported.
@ -230,8 +231,8 @@ headers.
The single address encoded by the header value. If the header value The single address encoded by the header value. If the header value
actually contains more than one address (which would be a violation of actually contains more than one address (which would be a violation of
the RFC under the default :mod:`policy`), accessing this attribute will the RFC under the default :mod:`~email.policy`), accessing this attribute
result in a :exc:`ValueError`. will result in a :exc:`ValueError`.
Many of the above classes also have a ``Unique`` variant (for example, Many of the above classes also have a ``Unique`` variant (for example,
@ -275,7 +276,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
.. class:: ContentTypeHeader .. class:: ContentTypeHeader
A :class:`ParameterizedMIMEHheader` class that handles the A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Type` header. :mailheader:`Content-Type` header.
.. attribute:: content_type .. attribute:: content_type
@ -289,7 +290,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
.. class:: ContentDispositionHeader .. class:: ContentDispositionHeader
A :class:`ParameterizedMIMEHheader` class that handles the A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Disposition` header. :mailheader:`Content-Disposition` header.
.. attribute:: content-disposition .. attribute:: content-disposition

11
Doc/library/email.iterators.rst
View file

@ -6,8 +6,9 @@
Iterating over a message object tree is fairly easy with the Iterating over a message object tree is fairly easy with the
:meth:`Message.walk` method. The :mod:`email.iterators` module provides some :meth:`Message.walk <email.message.Message.walk>` method. The
useful higher level iterations over message object trees. :mod:`email.iterators` module provides some useful higher level iterations over
message object trees.
.. function:: body_line_iterator(msg, decode=False) .. function:: body_line_iterator(msg, decode=False)
@ -16,9 +17,11 @@ useful higher level iterations over message object trees.
string payloads line-by-line. It skips over all the subpart headers, and it 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 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 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) .. function:: typed_subpart_iterator(msg, maintype='text', subtype=None)

14
Doc/library/email.message.rst
View file

@ -62,8 +62,8 @@ Here are the methods of the :class:`Message` class:
format the message the way you want. For example, by default it does 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 not do the mangling of lines that begin with ``From`` that is
required by the unix mbox format. For more flexibility, instantiate a required by the unix mbox format. For more flexibility, instantiate a
:class:`~email.generator.Generator` instance and use its :meth:`flatten` :class:`~email.generator.Generator` instance and use its
method directly. For example:: :meth:`~email.generator.Generator.flatten` method directly. For example::
from io import StringIO from io import StringIO
from email.generator import Generator from email.generator import Generator
@ -105,7 +105,8 @@ Here are the methods of the :class:`Message` class:
not do the mangling of lines that begin with ``From`` that is not do the mangling of lines that begin with ``From`` that is
required by the unix mbox format. For more flexibility, instantiate a required by the unix mbox format. For more flexibility, instantiate a
:class:`~email.generator.BytesGenerator` instance and use its :class:`~email.generator.BytesGenerator` instance and use its
:meth:`flatten` method directly. For example:: :meth:`~email.generator.BytesGenerator.flatten` method directly.
For example::
from io import BytesIO from io import BytesIO
from email.generator import BytesGenerator from email.generator import BytesGenerator
@ -530,8 +531,8 @@ Here are the methods of the :class:`Message` class:
Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
*boundary*. :meth:`set_boundary` will always quote *boundary* if *boundary*. :meth:`set_boundary` will always quote *boundary* if
necessary. A :exc:`HeaderParseError` is raised if the message object has necessary. A :exc:`~email.errors.HeaderParseError` is raised if the
no :mailheader:`Content-Type` header. message object has no :mailheader:`Content-Type` header.
Note that using this method is subtly different than deleting the old Note that using this method is subtly different than deleting the old
:mailheader:`Content-Type` header and adding a new one with the new :mailheader:`Content-Type` header and adding a new one with the new
@ -627,7 +628,8 @@ Here are the methods of the :class:`Message` class:
the end of the message. the end of the message.
You do not need to set the epilogue to the empty string in order for the 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 .. attribute:: defects

29
Doc/library/email.mime.rst
View file

@ -35,7 +35,8 @@ Here are the classes:
*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text` *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter 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 The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
(based on *_maintype*, *_subtype*, and *_params*), and a (based on *_maintype*, *_subtype*, and *_params*), and a
@ -50,8 +51,9 @@ Here are the classes:
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
class for MIME messages that are not :mimetype:`multipart`. The primary 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, purpose of this class is to prevent the use of the
which only makes sense for :mimetype:`multipart` messages. If :meth:`attach` :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. is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
@ -74,7 +76,8 @@ Here are the classes:
*_subparts* is a sequence of initial subparts for the payload. It must be *_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 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 Additional parameters for the :mailheader:`Content-Type` header are taken from
the keyword arguments, or passed into the *_params* argument, which is a keyword the keyword arguments, or passed into the *_params* argument, which is a keyword
@ -95,8 +98,10 @@ Here are the classes:
Optional *_encoder* is a callable (i.e. function) which will perform the actual 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 encoding of the data for transport. This callable takes one argument, which is
the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and the :class:`MIMEApplication` instance. It should use
:meth:`set_payload` to change the payload to encoded form. It should also add :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 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders. :mod:`email.encoders` module for a list of the built-in encoders.
@ -121,8 +126,10 @@ Here are the classes:
Optional *_encoder* is a callable (i.e. function) which will perform the actual 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, 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 which is the :class:`MIMEAudio` instance. It should use
:meth:`set_payload` to change the payload to encoded form. It should also add :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 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders. :mod:`email.encoders` module for a list of the built-in encoders.
@ -147,8 +154,10 @@ Here are the classes:
Optional *_encoder* is a callable (i.e. function) which will perform the actual 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, 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 which is the :class:`MIMEImage` instance. It should use
:meth:`set_payload` to change the payload to encoded form. It should also add :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 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders. :mod:`email.encoders` module for a list of the built-in encoders.

56
Doc/library/email.parser.rst
View file

@ -7,7 +7,8 @@
Message object structures can be created in one of two ways: they can be created 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 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. 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 The :mod:`email` package provides a standard parser that understands most email
@ -16,8 +17,9 @@ or a file object, and the parser will return to you the root
:class:`~email.message.Message` instance of the object structure. For simple, :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 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 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 return ``True`` from its :meth:`~email.message.Message.is_multipart` method, and
accessed via the :meth:`get_payload` and :meth:`walk` methods. 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 There are actually two parser interfaces available for use, the classic
:class:`Parser` API and the incremental :class:`FeedParser` API. The classic :class:`Parser` API and the incremental :class:`FeedParser` API. The classic
@ -134,7 +136,8 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
Read all the data from the file-like object *fp*, parse the resulting 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 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` The text contained in *fp* must be formatted as a block of :rfc:`2822`
style headers and header continuation lines, optionally preceded by a style headers and header continuation lines, optionally preceded by a
@ -173,8 +176,8 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
Read all the data from the binary file-like object *fp*, parse the Read all the data from the binary file-like object *fp*, parse the
resulting bytes, and return the message object. *fp* must support resulting bytes, and return the message object. *fp* must support
both the :meth:`readline` and the :meth:`read` methods on file-like both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
objects. methods on file-like objects.
The bytes contained in *fp* must be formatted as a block of :rfc:`2822` The bytes contained in *fp* must be formatted as a block of :rfc:`2822`
style headers and header continuation lines, optionally preceded by a style headers and header continuation lines, optionally preceded by a
@ -210,7 +213,7 @@ in the top-level :mod:`email` package namespace.
Return a message object structure from a string. This is exactly equivalent to Return a message object structure from a string. This is exactly equivalent to
``Parser().parsestr(s)``. *_class* and *policy* are interpreted as ``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 .. versionchanged:: 3.3
Removed the *strict* argument. Added the *policy* keyword. Removed the *strict* argument. Added the *policy* keyword.
@ -220,7 +223,8 @@ in the top-level :mod:`email` package namespace.
Return a message object structure from a byte string. This is exactly Return a message object structure from a byte string. This is exactly
equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and 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 .. versionadded:: 3.2
.. versionchanged:: 3.3 .. versionchanged:: 3.3
@ -231,7 +235,8 @@ in the top-level :mod:`email` package namespace.
Return a message object structure tree from an open :term:`file object`. Return a message object structure tree from an open :term:`file object`.
This is exactly equivalent to ``Parser().parse(fp)``. *_class* 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:: .. versionchanged::
Removed the *strict* argument. Added the *policy* keyword. Removed the *strict* argument. Added the *policy* keyword.
@ -241,8 +246,8 @@ in the top-level :mod:`email` package namespace.
Return a message object structure tree from an open binary :term:`file Return a message object structure tree from an open binary :term:`file
object`. This is exactly equivalent to ``BytesParser().parse(fp)``. object`. This is exactly equivalent to ``BytesParser().parse(fp)``.
*_class* and *policy* are interpreted as with the :class:`Parser` *_class* and *policy* are interpreted as with the
class constructor. :class:`~email.parser.Parser` class constructor.
.. versionadded:: 3.2 .. versionadded:: 3.2
.. versionchanged:: 3.3 .. versionchanged:: 3.3
@ -261,32 +266,35 @@ Here are some notes on the parsing semantics:
* Most non-\ :mimetype:`multipart` type messages are parsed as a single message * Most non-\ :mimetype:`multipart` type messages are parsed as a single message
object with a string payload. These objects will return ``False`` for object with a string payload. These objects will return ``False`` for
:meth:`is_multipart`. Their :meth:`get_payload` method will return a string :meth:`~email.message.Message.is_multipart`. Their
object. :meth:`~email.message.Message.get_payload` method will return a string object.
* All :mimetype:`multipart` type messages will be parsed as a container message * 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 object with a list of sub-message objects for their payload. The outer
container message will return ``True`` for :meth:`is_multipart` and their container message will return ``True`` for
:meth:`get_payload` method will return the list of :class:`~email.message.Message` :meth:`~email.message.Message.is_multipart` and their
subparts. :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. * Most messages with a content type of :mimetype:`message/\*` (e.g.
:mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
parsed as container object containing a list payload of length 1. Their parsed as container object containing a list payload of length 1. Their
:meth:`is_multipart` method will return ``True``. The single element in the :meth:`~email.message.Message.is_multipart` method will return ``True``.
list payload will be a sub-message object. The single element in the list payload will be a sub-message object.
* Some non-standards compliant messages may not be internally consistent about * Some non-standards compliant messages may not be internally consistent about
their :mimetype:`multipart`\ -edness. Such messages may have a their :mimetype:`multipart`\ -edness. Such messages may have a
:mailheader:`Content-Type` header of type :mimetype:`multipart`, but their :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
:meth:`is_multipart` method may return ``False``. If such messages were parsed :meth:`~email.message.Message.is_multipart` method may return ``False``.
with the :class:`FeedParser`, they will have an instance of the If such messages were parsed with the :class:`~email.parser.FeedParser`,
:class:`MultipartInvariantViolationDefect` class in their *defects* attribute they will have an instance of the
list. See :mod:`email.errors` for details. :class:`~email.errors.MultipartInvariantViolationDefect` class in their
*defects* attribute list. See :mod:`email.errors` for details.
.. rubric:: Footnotes .. rubric:: Footnotes
.. [#] As of email package version 3.0, introduced in Python 2.4, the classic .. [#] 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 :class:`~email.parser.Parser` was re-implemented in terms of the
semantics and results are identical between the two parsers. :class:`~email.parser.FeedParser`, so the semantics and results are
identical between the two parsers.

9
Doc/library/email.policy.rst
View file

@ -315,7 +315,7 @@ added matters. To illustrate::
This concrete :class:`Policy` is the backward compatibility policy. It This concrete :class:`Policy` is the backward compatibility policy. It
replicates the behavior of the email package in Python 3.2. The 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 :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. behavior of the email package is to maintain compatibility with Python 3.2.
@ -459,10 +459,11 @@ added matters. To illustrate::
.. method:: fold_binary(name, value) .. method:: fold_binary(name, value)
The same as :meth:`fold` if :attr:`cte_type` is ``7bit``, except that The same as :meth:`fold` if :attr:`~Policy.cte_type` is ``7bit``, except
the returned value is bytes. 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 into bytes. Headers with binary data are not refolded, regardless of the
``refold_header`` setting, since there is no way to know whether the ``refold_header`` setting, since there is no way to know whether the
binary data consists of single byte characters or multibyte characters. binary data consists of single byte characters or multibyte characters.

181
Doc/library/email.rst
View file

@ -147,14 +147,15 @@ Here are the major differences between :mod:`email` version 4 and version 3:
*Note that the version 3 names will continue to work until Python 2.6*. *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 * 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 * Methods that were deprecated in version 3 have been removed. These include
:meth:`Generator.__call__`, :meth:`Message.get_type`, :meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`. :meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
* Fixes have been added for :rfc:`2231` support which can change some of the * 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 circumstances, values which used to return a 3-tuple now return simple strings
(specifically, if all extended parameter segments were unencoded, there is no (specifically, if all extended parameter segments were unencoded, there is no
language and charset designation expected, so the return type is now a simple 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 4 and version 3:
Here are the major differences between :mod:`email` version 3 and version 2: Here are the major differences between :mod:`email` version 3 and version 2:
* The :class:`FeedParser` class was introduced, and the :class:`Parser` class * The :class:`~email.parser.FeedParser` class was introduced, and the
was implemented in terms of the :class:`FeedParser`. All parsing therefore is :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. 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* Problems found while parsing messages are stored in the message's *defect*
attribute. attribute.
* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2 * All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
have been removed. These include the *_encoder* argument to the have been removed. These include the *_encoder* argument to the
:class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the :class:`~email.mime.text.MIMEText` constructor, the
:func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decode` :meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair`
and :func:`Utils.encode`. function, and the functions :func:`Utils.decode` and :func:`Utils.encode`.
* New :exc:`DeprecationWarning`\ s have been added to: * New :exc:`DeprecationWarning`\ s have been added to:
:meth:`Generator.__call__`, :meth:`Message.get_type`, :meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict* :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 argument to the :class:`~email.parser.Parser` class. These are expected to
future versions. be removed in future versions.
* Support for Pythons earlier than 2.3 has been removed. * Support for Pythons earlier than 2.3 has been removed.
@ -187,53 +189,61 @@ Here are the differences between :mod:`email` version 2 and version 1:
* The :mod:`email.Header` and :mod:`email.Charset` modules have been added. * The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
* The pickle format for :class:`Message` instances has changed. Since this was * The pickle format for :class:`~email.message.Message` instances has changed.
never (and still isn't) formally defined, this isn't considered a backward Since this was never (and still isn't) formally defined, this isn't
incompatibility. However if your application pickles and unpickles considered a backward incompatibility. However if your application pickles
:class:`Message` instances, be aware that in :mod:`email` version 2, and unpickles :class:`~email.message.Message` instances, be aware that in
:class:`Message` instances now have private variables *_charset* and :mod:`email` version 2, :class:`~email.message.Message` instances now have
*_default_type*. private variables *_charset* and *_default_type*.
* Several methods in the :class:`Message` class have been deprecated, or their * Several methods in the :class:`~email.message.Message` class have been
signatures changed. Also, many new methods have been added. See the deprecated, or their signatures changed. Also, many new methods have been
documentation for the :class:`Message` class for details. The changes should be added. See the documentation for the :class:`~email.message.Message` class
completely backward compatible. for details. The changes should be completely backward compatible.
* The object structure has changed in the face of :mimetype:`message/rfc822` * 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 content types. In :mod:`email` version 1, such a type would be represented
scalar payload, i.e. the container message's :meth:`is_multipart` returned by a scalar payload, i.e. the container message's
false, :meth:`get_payload` was not a list object, but a single :class:`Message` :meth:`~email.message.Message.is_multipart` returned false,
instance. :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 This structure was inconsistent with the rest of the package, so the object
representation for :mimetype:`message/rfc822` content types was changed. In representation for :mimetype:`message/rfc822` content types was changed. In
:mod:`email` version 2, the container *does* return ``True`` from :mod:`email` version 2, the container *does* return ``True`` from
:meth:`is_multipart`, and :meth:`get_payload` returns a list containing a single :meth:`~email.message.Message.is_multipart`, and
:class:`Message` item. :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 Note that this is one place that backward compatibility could not be
maintained. However, if you're already testing the return type of 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 :meth:`~email.message.Message.get_payload`, you should be fine. You just need
doesn't do a :meth:`set_payload` with a :class:`Message` instance on a container to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
with a content type of :mimetype:`message/rfc822`. 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 * The :class:`~email.parser.Parser` constructor's *strict* argument was added,
:meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The and its :meth:`~email.parser.Parser.parse` and
*strict* flag was also added to functions :func:`email.message_from_file` and :meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument.
:func:`email.message_from_string`. 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` * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten
instead. The :class:`Generator` class has also grown the :meth:`clone` method. <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 * The :class:`~email.generator.DecodedGenerator` class in the
added. :mod:`email.generator` module was added.
* The intermediate base classes :class:`MIMENonMultipart` and * The intermediate base classes
:class:`MIMEMultipart` have been added, and interposed in the class hierarchy :class:`~email.mime.nonmultipart.MIMENonMultipart` and
for most of the other MIME-related derived classes. :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 * The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor
deprecated. Encoding now happens implicitly based on the *_charset* argument. has been deprecated. Encoding now happens implicitly based on the
*_charset* argument.
* The following functions in the :mod:`email.Utils` module have been deprecated: * The following functions in the :mod:`email.Utils` module have been deprecated:
:func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
@ -266,17 +276,22 @@ package has the following differences:
* :func:`messageFromFile` has been renamed to :func:`message_from_file`. * :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`. * The method :meth:`gettype` was renamed to :meth:`get_type`.
@ -284,48 +299,57 @@ The :class:`Message` class has the following differences:
* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`. * The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
* The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas * The method :meth:`getparams` was renamed to
:meth:`getparams` returned a list of strings, :meth:`get_params` returns a list :meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
of 2-tuples, effectively the key/value pairs of the parameters, split on the returned a list of strings, :meth:`~email.message.Message.get_params` returns
``'='`` sign. 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 * The method :meth:`getdecodedpayload` was removed. To get similar
functionality, pass the value 1 to the *decode* flag of the get_payload() functionality, pass the value 1 to the *decode* flag of the
method. :meth:`~email.message.Message.get_payload` method.
* The method :meth:`getpayloadastext` was removed. Similar functionality is * 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
module. :mod:`email.generator` module.
* The method :meth:`getbodyastext` was removed. You can get similar * The method :meth:`getbodyastext` was removed. You can get similar
functionality by creating an iterator with :func:`typed_subpart_iterator` in the functionality by creating an iterator with
:mod:`email.iterators` module. :func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators`
module.
The :class:`Parser` class has no differences in its public interface. It does The :class:`~email.parser.Parser` class has no differences in its public
have some additional smarts to recognize :mimetype:`message/delivery-status` interface. It does have some additional smarts to recognize
type messages, which it represents as a :class:`Message` instance containing :mimetype:`message/delivery-status` type messages, which it represents as a
separate :class:`Message` subparts for each header block in the delivery status :class:`~email.message.Message` instance containing separate
notification [#]_. :class:`~email.message.Message` subparts for each header block in the delivery
status notification [#]_.
The :class:`Generator` class has no differences in its public interface. There The :class:`~email.generator.Generator` class has no differences in its public
is a new class in the :mod:`email.generator` module though, called interface. There is a new class in the :mod:`email.generator` module though,
:class:`DecodedGenerator` which provides most of the functionality previously called :class:`~email.generator.DecodedGenerator` which provides most of the
available in the :meth:`Message.getpayloadastext` method. functionality previously available in the :meth:`Message.getpayloadastext`
method.
The following modules and classes have been changed: The following modules and classes have been changed:
* The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have * The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major*
changed to *_maintype* and *_subtype* respectively. and *_minor* have changed to *_maintype* and *_subtype* respectively.
* The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor* * The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
argument has been renamed to *_subtype*. argument has been renamed to *_subtype*.
@ -338,7 +362,8 @@ The following modules and classes have been changed:
but that clashed with the Python standard library module :mod:`rfc822` on some but that clashed with the Python standard library module :mod:`rfc822` on some
case-insensitive file systems. 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* with main type :mimetype:`message`. It takes an optional argument *_subtype*
which is used to set the MIME subtype. *_subtype* defaults to which is used to set the MIME subtype. *_subtype* defaults to
:mimetype:`rfc822`. :mimetype:`rfc822`.
@ -348,8 +373,8 @@ The following modules and classes have been changed:
:mod:`email.utils` module. :mod:`email.utils` module.
The ``MsgReader`` class/module has been removed. Its functionality is most The ``MsgReader`` class/module has been removed. Its functionality is most
closely supported in the :func:`body_line_iterator` function in the closely supported in the :func:`~email.iterators.body_line_iterator` function
:mod:`email.iterators` module. in the :mod:`email.iterators` module.
.. rubric:: Footnotes .. rubric:: Footnotes

9
Doc/library/email.util.rst
View file

@ -49,8 +49,8 @@ There are several useful utilities provided in the :mod:`email.utils` module:
This method returns a list of 2-tuples of the form returned by ``parseaddr()``. 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 *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 :meth:`Message.get_all <email.message.Message.get_all>`. Here's a simple
of a message:: example that gets all the recipients of a message::
from email.utils import getaddresses from email.utils import getaddresses
@ -187,10 +187,11 @@ There are several useful utilities provided in the :mod:`email.utils` module:
.. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii') .. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')
When a header parameter is encoded in :rfc:`2231` format, 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 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 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 *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'``. :rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``.