summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorR David Murray <rdmurray@bitdance.com>2011-04-18 20:00:47 (GMT)
committerR David Murray <rdmurray@bitdance.com>2011-04-18 20:00:47 (GMT)
commit6a45d3b6ae46291a2ee6d07fe67f5603cf8a1515 (patch)
treeaf5cd1ac4be543574999aee2ed271931047075fe
parent1f056b248a6f30d7a9b3ae265e24c9a7e8dc2711 (diff)
downloadcpython-6a45d3b6ae46291a2ee6d07fe67f5603cf8a1515.zip
cpython-6a45d3b6ae46291a2ee6d07fe67f5603cf8a1515.tar.gz
cpython-6a45d3b6ae46291a2ee6d07fe67f5603cf8a1515.tar.bz2
Markup and text fixes from Georg Brandl's review.
-rw-r--r--Doc/library/email.parser.rst15
-rw-r--r--Doc/library/email.policy.rst49
2 files changed, 36 insertions, 28 deletions
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index c5e43a9..e70b429 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -211,16 +211,19 @@ in the top-level :mod:`email` package namespace.
``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 @@ in the top-level :mod:`email` package namespace.
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 @@ in the top-level :mod:`email` package namespace.
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
index f7eb471..f95af39 100644
--- 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 @@ email. Some of these uses conform fairly closely to the main RFCs, some do
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 @@ program will use the same :class:`Policy` for both input and output, the two
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 @@ added matters. To illustrate::
.. 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 @@ added matters. To illustrate::
: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 @@ added matters. To illustrate::
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 @@ added matters. To illustrate::
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`.