Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
C
cpython
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
Kirill Smelkov
cpython
Commits
dcd4dfbf
Commit
dcd4dfbf
authored
Aug 19, 2013
by
Serhiy Storchaka
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Issue #18761: Improved cross-references in email documentation.
parent
36d89cc4
Changes
10
Expand all
Hide whitespace changes
Inline
Side-by-side
Showing
10 changed files
with
208 additions
and
156 deletions
+208
-156
Doc/library/email.charset.rst
Doc/library/email.charset.rst
+1
-1
Doc/library/email.errors.rst
Doc/library/email.errors.rst
+16
-13
Doc/library/email.headerregistry.rst
Doc/library/email.headerregistry.rst
+8
-7
Doc/library/email.iterators.rst
Doc/library/email.iterators.rst
+7
-4
Doc/library/email.message.rst
Doc/library/email.message.rst
+6
-5
Doc/library/email.mime.rst
Doc/library/email.mime.rst
+19
-10
Doc/library/email.parser.rst
Doc/library/email.parser.rst
+32
-24
Doc/library/email.policy.rst
Doc/library/email.policy.rst
+5
-4
Doc/library/email.rst
Doc/library/email.rst
+109
-84
Doc/library/email.util.rst
Doc/library/email.util.rst
+5
-4
No files found.
Doc/library/email.charset.rst
View file @
dcd4dfbf
...
...
@@ -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
Python codec, as appropriate for the second argument to the :class:`str`'s
:
func:`de
code` method
:
meth:`~str.en
code` method
Doc/library/email.errors.rst
View file @
dcd4dfbf
...
...
@@ -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
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 @@ 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
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 @@ The following exception classes are defined in the :mod:`email.errors` module:
.. 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` o
r
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 eithe
r
: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 class is *not* an exception!
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
...
...
Doc/library/email.headerregistry.rst
View file @
dcd4dfbf
...
...
@@ -56,15 +56,16 @@ headers.
.. 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 @@ headers.
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 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
.. class:: ContentTypeHeader
A :class:`ParameterizedMIMEH
h
eader` class that handles the
A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Type` header.
.. attribute:: content_type
...
...
@@ -289,7 +290,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
.. class:: ContentDispositionHeader
A :class:`ParameterizedMIMEH
h
eader` class that handles the
A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Disposition` header.
.. attribute:: content-disposition
...
...
Doc/library/email.iterators.rst
View file @
dcd4dfbf
...
...
@@ -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 @@ useful higher level iterations over message object trees.
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)
...
...
Doc/library/email.message.rst
View file @
dcd4dfbf
...
...
@@ -55,8 +55,8 @@ Here are the methods of the :class:`Message` class:
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 @@ Here are the methods of the :class:`Message` class:
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 @@ Here are the methods of the :class:`Message` class:
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
...
...
Doc/library/email.mime.rst
View file @
dcd4dfbf
...
...
@@ -35,7 +35,8 @@ Here are the classes:
*_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 @@ Here are the classes:
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 @@ Here are the classes:
*_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 @@ Here are the classes:
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 @@ Here are the classes:
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 @@ Here are the classes:
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.
...
...
Doc/library/email.parser.rst
View file @
dcd4dfbf
...
...
@@ -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 @@ 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.
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 @@ 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
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 @@ 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
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 @@ in the top-level :mod:`email` package namespace.
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 @@ in the top-level :mod:`email` package namespace.
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 @@ in the top-level :mod:`email` package namespace.
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 @@ in the top-level :mod:`email` package namespace.
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 @@ Here are some notes on the parsing semantics:
* 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.
Doc/library/email.policy.rst
View file @
dcd4dfbf
...
...
@@ -304,7 +304,7 @@ added matters. To illustrate::
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 @@ added matters. To illustrate::
.. method:: fold_binary(name, value)
The same as :meth:`fold` if :attr:`
cte_type` is ``7bit``, except tha
t
the returned value is bytes.
The same as :meth:`fold` if :attr:`
~Policy.cte_type` is ``7bit``, excep
t
th
at th
e 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.
...
...
Doc/library/email.rst
View file @
dcd4dfbf
This diff is collapsed.
Click to expand it.
Doc/library/email.util.rst
View file @
dcd4dfbf
...
...
@@ -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()``.
*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 @@ There are several useful utilities provided in the :mod:`email.utils` module:
.. 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'``.
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment