traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

#21300: Clean up the docs for the email "policy" arguments.

This commit is contained in:
R David Murray 2014-05-06 21:33:18 -04:00
parent 3d139d8ed6
commit e25244657c
3 changed files with 37 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Doc/library/email.generator.rst
View File

@ -112,7 +112,7 @@ formatted string representation of a message object. For more detail, see
:mod:`email.message`.
.. class:: BytesGenerator(outfp, mangle_from_=True, maxheaderlen=78, *, \
policy=policy.default)
policy=None)
The constructor for the :class:`BytesGenerator` class takes a binary
:term:`file-like object` called *outfp* for an argument. *outfp* must
@ -134,9 +134,11 @@ formatted string representation of a message object. For more detail, see
wrapping. The default is 78, as recommended (but not required) by
:rfc:`2822`.
The *policy* keyword specifies a :mod:`~email.policy` object that controls a
number of aspects of the generator's operation. The default policy
maintains backward compatibility.
number of aspects of the generator's operation. If no *policy* is specified,
then the *policy* attached to the message object passed to :attr:`flatten`
is used.
.. versionchanged:: 3.3 Added the *policy* keyword.
@ -174,7 +176,7 @@ formatted string representation of a message object. For more detail, see
Optional *linesep* specifies the line separator character used to
terminate lines in the output. If specified it overrides the value
specified by the ``Generator``\ 's ``policy``.
specified by the ``Generator``\ or *msg*\ 's ``policy``.
.. method:: clone(fp)

41
Doc/library/email.parser.rst
View File

@ -60,15 +60,18 @@ list of defects that it can find.
Here is the API for the :class:`FeedParser`:
.. class:: FeedParser(_factory=email.message.Message, *, policy=policy.default)
.. class:: FeedParser(_factory=email.message.Message, *, policy=policy.compat32)
Create a :class:`FeedParser` instance. Optional *_factory* is a no-argument
callable that will be called whenever a new message object is needed. It
defaults to the :class:`email.message.Message` class.
The *policy* keyword specifies a :mod:`~email.policy` object that controls a
number of aspects of the parser's operation. The default policy maintains
backward compatibility.
If *policy* is specified (it must be an instance of a :mod:`~email.policy`
class) use the rules it specifies to udpate the representation of the
message. If *policy* is not set, use the :class:`compat32
<email.policy.Compat32>` policy, which maintains backward compatibility with
the Python 3.2 version of the email package. For more information see the
:mod:`~email.policy` documentation.
.. versionchanged:: 3.3 Added the *policy* keyword.
@ -113,7 +116,7 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
The BytesHeaderParser class.
.. class:: Parser(_class=email.message.Message, *, policy=policy.default)
.. class:: Parser(_class=email.message.Message, *, policy=policy.compat32)
The constructor for the :class:`Parser` class takes an optional argument
*_class*. This must be a callable factory (such as a function or a class), and
@ -121,9 +124,12 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
:class:`~email.message.Message` (see :mod:`email.message`). The factory will
be called without arguments.
The *policy* keyword specifies a :mod:`~email.policy` object that controls a
number of aspects of the parser's operation. The default policy maintains
backward compatibility.
If *policy* is specified (it must be an instance of a :mod:`~email.policy`
class) use the rules it specifies to udpate the representation of the
message. If *policy* is not set, use the :class:`compat32
<email.policy.Compat32>` policy, which maintains backward compatibility with
the Python 3.2 version of the email package. For more information see the
:mod:`~email.policy` documentation.
.. versionchanged:: 3.3
Removed the *strict* argument that was deprecated in 2.4. Added the
@ -159,15 +165,18 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
Optional *headersonly* is as with the :meth:`parse` method.
.. class:: BytesParser(_class=email.message.Message, *, policy=policy.default)
.. class:: BytesParser(_class=email.message.Message, *, policy=policy.compat32)
This class is exactly parallel to :class:`Parser`, but handles bytes input.
The *_class* and *strict* arguments are interpreted in the same way as for
the :class:`Parser` constructor.
The *policy* keyword specifies a :mod:`~email.policy` object that
controls a number of aspects of the parser's operation. The default
policy maintains backward compatibility.
If *policy* is specified (it must be an instance of a :mod:`~email.policy`
class) use the rules it specifies to udpate the representation of the
message. If *policy* is not set, use the :class:`compat32
<email.policy.Compat32>` policy, which maintains backward compatibility with
the Python 3.2 version of the email package. For more information see the
:mod:`~email.policy` documentation.
.. versionchanged:: 3.3
Removed the *strict* argument. Added the *policy* keyword.
@ -209,7 +218,7 @@ in the top-level :mod:`email` package namespace.
.. currentmodule:: email
.. function:: message_from_string(s, _class=email.message.Message, *, \
policy=policy.default)
policy=policy.compat32)
Return a message object structure from a string. This is exactly equivalent to
``Parser().parsestr(s)``. *_class* and *policy* are interpreted as
@ -219,7 +228,7 @@ in the top-level :mod:`email` package namespace.
Removed the *strict* argument. Added the *policy* keyword.
.. function:: message_from_bytes(s, _class=email.message.Message, *, \
policy=policy.default)
policy=policy.compat32)
Return a message object structure from a byte string. This is exactly
equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and
@ -231,7 +240,7 @@ in the top-level :mod:`email` package namespace.
Removed the *strict* argument. Added the *policy* keyword.
.. function:: message_from_file(fp, _class=email.message.Message, *, \
policy=policy.default)
policy=policy.compat32)
Return a message object structure tree from an open :term:`file object`.
This is exactly equivalent to ``Parser().parse(fp)``. *_class*
@ -242,7 +251,7 @@ in the top-level :mod:`email` package namespace.
Removed the *strict* argument. Added the *policy* keyword.
.. function:: message_from_binary_file(fp, _class=email.message.Message, *, \
policy=policy.default)
policy=policy.compat32)
Return a message object structure tree from an open binary :term:`file
object`. This is exactly equivalent to ``BytesParser().parse(fp)``.

9
Lib/email/generator.py
View File

@ -51,8 +51,9 @@ class Generator:
by RFC 2822.
The policy keyword specifies a policy object that controls a number of
aspects of the generator's operation. The default policy maintains
backward compatibility.
aspects of the generator's operation. If no policy is specified,
the policy associated with the Message object passed to the
flatten method is used.
"""
self._fp = outfp
@ -76,7 +77,9 @@ class Generator:
Note that for subobjects, no From_ line is printed.
linesep specifies the characters used to indicate a new line in
the output. The default value is determined by the policy.
the output. The default value is determined by the policy specified
when the Generator instance was created or, if none was specified,
from the policy associated with the msg.
"""
# We use the _XXX constants for operating on data that comes directly