``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)
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)
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::
.. 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
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.
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::
.. 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
: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
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
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`.
projects / python / commitdiff