[Python-checkins] cpython (3.4): #21300: Clean up the docs for the email "policy" arguments.
r.david.murray
python-checkins at python.org
Wed May 7 03:34:18 CEST 2014
http://hg.python.org/cpython/rev/d994d75cce95
changeset: 90577:d994d75cce95
branch: 3.4
parent: 90575:afe8c4bd3230
user: R David Murray <rdmurray at bitdance.com>
date: Tue May 06 21:33:18 2014 -0400
summary:
#21300: Clean up the docs for the email "policy" arguments.
files:
Doc/library/email.generator.rst | 10 +++--
Doc/library/email.parser.rst | 41 ++++++++++++--------
Lib/email/generator.py | 9 +++-
3 files changed, 37 insertions(+), 23 deletions(-)
diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst
--- a/Doc/library/email.generator.rst
+++ b/Doc/library/email.generator.rst
@@ -112,7 +112,7 @@
: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 @@
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 @@
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)
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
@@ -60,15 +60,18 @@
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 @@
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 @@
: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 @@
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 @@
.. 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 @@
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 @@
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 @@
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)``.
diff --git a/Lib/email/generator.py b/Lib/email/generator.py
--- a/Lib/email/generator.py
+++ b/Lib/email/generator.py
@@ -51,8 +51,9 @@
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 @@
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
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list