[Python-checkins] cpython: Markup and text fixes from Georg Brandl's review.
r.david.murray
python-checkins at python.org
Mon Apr 18 22:01:02 CEST 2011
http://hg.python.org/cpython/rev/2127df2c972e
changeset: 69431:2127df2c972e
user: R David Murray <rdmurray at bitdance.com>
date: Mon Apr 18 16:00:47 2011 -0400
summary:
Markup and text fixes from Georg Brandl's review.
files:
Doc/library/email.parser.rst | 15 ++++--
Doc/library/email.policy.rst | 49 ++++++++++++-----------
2 files changed, 36 insertions(+), 28 deletions(-)
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
@@ -211,16 +211,19 @@
``Parser().parsestr(s)``. *_class* and *policy* are interpreted as
with the :class:`Parser` class constructor.
- .. versionchanged:: removed *strict*, added *policy*
+ .. versionchanged:: 3.3
+ Removed the *strict* argument. Added the *policy* keyword.
-.. function:: message_from_bytes(s, _class=email.message.Message, strict=None)
+.. function:: message_from_bytes(s, _class=email.message.Message, *, \
+ policy=policy.default)
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.
.. versionadded:: 3.2
- .. versionchanged:: 3.3 removed *strict*, added *policy*
+ .. versionchanged:: 3.3
+ Removed the *strict* argument. Added the *policy* keyword.
.. function:: message_from_file(fp, _class=email.message.Message, *, \
policy=policy.default)
@@ -229,7 +232,8 @@
This is exactly equivalent to ``Parser().parse(fp)``. *_class*
and *policy* are interpreted as with the :class:`Parser` class constructor.
- .. versionchanged:: 3.3 removed *strict*, added *policy*
+ .. versionchanged::
+ Removed the *strict* argument. Added the *policy* keyword.
.. function:: message_from_binary_file(fp, _class=email.message.Message, *, \
policy=policy.default)
@@ -240,7 +244,8 @@
class constructor.
.. versionadded:: 3.2
- .. versionchanged:: 3.3 removed *strict*, added *policy*
+ .. versionchanged:: 3.3
+ Removed the *strict* argument. Added the *policy* keyword.
Here's an example of how you might use this at an interactive Python prompt::
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
@@ -4,6 +4,8 @@
.. module:: email.policy
:synopsis: Controlling the parsing and generating of messages
+.. versionadded: 3.3
+
The :mod:`email` package's prime focus is the handling of email messages as
described by the various email and MIME RFCs. However, the general format of
@@ -14,8 +16,8 @@
not. And even when working with email, there are times when it is desirable to
break strict compliance with the RFCs.
-Policy objects are the mechanism used to provide the email package with the
-flexibility to handle all these disparate use cases,
+Policy objects give the email package the flexibility to handle all these
+disparate use cases.
A :class:`Policy` object encapsulates a set of attributes and methods that
control the behavior of various components of the email package during use.
@@ -39,24 +41,23 @@
can be different.
As an example, the following code could be used to read an email message from a
-file on disk and pass it to the system ``sendmail`` program on a ``unix``
-system::
+file on disk and pass it to the system ``sendmail`` program on a Unix system::
>>> from email import msg_from_binary_file
>>> from email.generator import BytesGenerator
>>> import email.policy
>>> from subprocess import Popen, PIPE
>>> with open('mymsg.txt', 'b') as f:
- >>> msg = msg_from_binary_file(f, policy=email.policy.mbox)
+ ... Msg = msg_from_binary_file(f, policy=email.policy.mbox)
>>> p = Popen(['sendmail', msg['To'][0].address], stdin=PIPE)
- >>> g = BytesGenerator(p.stdin, email.policy.policy=SMTP)
+ >>> g = BytesGenerator(p.stdin, policy=email.policy.SMTP)
>>> g.flatten(msg)
>>> p.stdin.close()
>>> rc = p.wait()
Some email package methods accept a *policy* keyword argument, allowing the
-policy to be overridden for that method. For example, the following code use
-the :meth:`email.message.Message.as_string` method to the *msg* object from the
+policy to be overridden for that method. For example, the following code uses
+the :meth:`email.message.Message.as_string` method of the *msg* object from the
previous example and re-write it to a file using the native line separators for
the platform on which it is running::
@@ -106,19 +107,19 @@
.. attribute:: linesep
The string to be used to terminate lines in serialized output. The
- default is '\\n' because that's the internal end-of-line discipline used
- by Python, though '\\r\\n' is required by the RFCs. See `Policy
+ default is ``\n`` because that's the internal end-of-line discipline used
+ by Python, though ``\r\n`` is required by the RFCs. See `Policy
Instances`_ for policies that use an RFC conformant linesep. Setting it
to :attr:`os.linesep` may also be useful.
.. attribute:: must_be_7bit
- If :const:`True`, data output by a bytes generator is limited to ASCII
+ If ``True``, data output by a bytes generator is limited to ASCII
characters. If :const:`False` (the default), then bytes with the high
bit set are preserved and/or allowed in certain contexts (for example,
where possible a content transfer encoding of ``8bit`` will be used).
- String generators act as if ``must_be_7bit`` is `True` regardless of the
- policy in effect, since a string cannot represent non-ASCII bytes.
+ String generators act as if ``must_be_7bit`` is ``True`` regardless of
+ the policy in effect, since a string cannot represent non-ASCII bytes.
.. attribute:: raise_on_defect
@@ -126,6 +127,8 @@
:const:`False` (the default), defects will be passed to the
:meth:`register_defect` method.
+ :mod:`Policy` object also have the following methods:
+
.. method:: handle_defect(obj, defect)
*obj* is the object on which to register the defect. *defect* should be
@@ -145,7 +148,7 @@
handling of defects. The default implementation calls the ``append``
method of the ``defects`` attribute of *obj*.
- .. method:: clone(obj, *kw):
+ .. method:: clone(obj, *kw)
Return a new :class:`Policy` instance whose attributes have the same
values as the current instance, except where those attributes are
@@ -153,27 +156,27 @@
Policy Instances
-................
+^^^^^^^^^^^^^^^^
The following instances of :class:`Policy` provide defaults suitable for
specific common application domains.
.. data:: default
- An instance of :class:`Policy` with all defaults unchanged.
+ An instance of :class:`Policy` with all defaults unchanged.
.. data:: SMTP
- Output serialized from a message will conform to the email and SMTP
- RFCs. The only changed attribute is :attr:`linesep`, which is set to
- ``\r\n``.
+ Output serialized from a message will conform to the email and SMTP
+ RFCs. The only changed attribute is :attr:`linesep`, which is set to
+ ``\r\n``.
.. data:: HTTP
- Suitable for use when serializing headers for use in HTTP traffic.
- :attr:`linesep` is set to ``\r\n``, and :attr:`max_line_length` is set to
- :const:`None` (unlimited).
+ Suitable for use when serializing headers for use in HTTP traffic.
+ :attr:`linesep` is set to ``\r\n``, and :attr:`max_line_length` is set to
+ :const:`None` (unlimited).
.. data:: strict
- :attr:`raise_on_defect` is set to :const:`True`.
+ :attr:`raise_on_defect` is set to :const:`True`.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list