:mod:`email`: Policy Objects ---------------------------- .. 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 email messages (a block of header fields each consisting of a name followed by a colon followed by a value, the whole block followed by a blank line and an arbitrary 'body'), is a format that has found utility outside of the realm of 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 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. :class:`Policy` instances can be passed to various classes and methods in the email package to alter the default behavior. The settable values and their defaults are described below. The :mod:`policy` module also provides some pre-created :class:`Policy` instances. In addition to a :const:`default` instance, there are instances tailored for certain applications. For example there is an :const:`SMTP` :class:`Policy` with defaults appropriate for generating output to be sent to an SMTP server. These are listed `below `. In general an application will only need to deal with setting the policy at the input and output boundaries. Once parsed, a message is represented by a :class:`~email.message.Message` object, which is designed to be independent of the format that the message has "on the wire" when it is received, transmitted, or displayed. Thus, a :class:`Policy` can be specified when parsing a message to create a :class:`~email.message.Message`, and again when turning the :class:`~email.message.Message` into some other representation. While often a 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:: >>> 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) >>> p = Popen(['sendmail', msg['To'][0].address], stdin=PIPE) >>> g = BytesGenerator(p.stdin, policy=email.policy.SMTP) >>> g.flatten(msg) >>> p.stdin.close() >>> rc = p.wait() .. XXX email.policy.mbox/MBOX does not exist yet Some email package methods accept a *policy* keyword argument, allowing 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:: >>> import os >>> mypolicy = email.policy.Policy(linesep=os.linesep) >>> with open('converted.txt', 'wb') as f: ... f.write(msg.as_string(policy=mypolicy)) Policy instances are immutable, but they can be cloned, accepting the same keyword arguments as the class constructor and returning a new :class:`Policy` instance that is a copy of the original but with the specified attributes values changed. For example, the following creates an SMTP policy that will raise any defects detected as errors:: >>> strict_SMTP = email.policy.SMTP.clone(raise_on_defect=True) Policy objects can also be combined using the addition operator, producing a policy object whose settings are a combination of the non-default values of the summed objects:: >>> strict_SMTP = email.policy.SMTP + email.policy.strict This operation is not commutative; that is, the order in which the objects are added matters. To illustrate:: >>> Policy = email.policy.Policy >>> apolicy = Policy(max_line_length=100) + Policy(max_line_length=80) >>> apolicy.max_line_length 80 >>> apolicy = Policy(max_line_length=80) + Policy(max_line_length=100) >>> apolicy.max_line_length 100 .. class:: Policy(**kw) The valid constructor keyword arguments are any of the attributes listed below. .. attribute:: max_line_length The maximum length of any line in the serialized output, not counting the end of line character(s). Default is 78, per :rfc:`5322`. A value of ``0`` or :const:`None` indicates that no line wrapping should be done at all. .. 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 Instances`_ for policies that use an RFC conformant linesep. Setting it to :attr:`os.linesep` may also be useful. .. attribute:: must_be_7bit 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. .. attribute:: raise_on_defect If :const:`True`, any defects encountered will be raised as errors. If :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 an instance of a subclass of :class:`~email.errors.Defect`. If :attr:`raise_on_defect` is ``True`` the defect is raised as an exception. Otherwise *obj* and *defect* are passed to :meth:`register_defect`. This method is intended to be called by parsers when they encounter defects, and will not be called by code that uses the email library unless that code is implementing an alternate parser. .. method:: register_defect(obj, defect) *obj* is the object on which to register the defect. *defect* should be a subclass of :class:`~email.errors.Defect`. This method is part of the public API so that custom ``Policy`` subclasses can implement alternate handling of defects. The default implementation calls the ``append`` method of the ``defects`` attribute of *obj*. .. 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 given new values by the keyword arguments. 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. .. 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``. .. 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). .. data:: strict :attr:`raise_on_defect` is set to :const:`True`.