:mod:`email`: Policy Objects ---------------------------- .. module:: email.policy :synopsis: Controlling the parsing and generating of messages The :mod:`email` module'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 hew 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, A policy object encapsulates a set of attributes and methods that control the behavior of the various components of the email package during use. There are two base classes for policy objects: :class:`Policy` and :class:`PolicySet`. :class:`Policy` provides a constructor that allows the setting of policy attributes via keyword arguments, but no default values or default method implementations. :class:`PolicySet` provides a full set of default values and method implementations. Almost every object created by the email package will have an associated :attr:`policy` attribute, which should be a :class:`PolicySet` instance. When an application wishes to change the default policy for all objects it creates, it can create an instance of :class:`PolicySet` (or of a subclass of it) with the non-default attribute values overridden, and use that to initialize the :attr:`policy` attribute of the objects it creates. For the most part the setting of the :attr:`policy` attribute on sub-objects happens automatically during the construction of a message, so in practice this means that the application-specific default policy needs to be passed to the message class constructor. Many of the email package object methods accept a *policy* keyword-only argument. Under most circumstances the correct thing to pass to this argument is an instance of :class:`Policy` (or of a subclass of it). Any attributes (or methods for a subclass) present on the :class:`Policy` instance will override those from the object's default policy. Objects in the email package that have a :attr:`policy` attribute also have a :attr:`policy_override` attribute. This attribute is usually :const:`None`, but can contain (or be set to) an object derived from :class:`Policy`. Any attributes or methods on the :attr:`policy_override` object will override the corresponding attributes from the default :attr:`policy`. Certain object types use this to override certain defaults [#]_. This mechanism can also be used by an application to set overrides on objects before attaching them to other objects (for example, setting an override on a header object before passing it to a message's :meth:`set_header` method). If an application wants to ignore all :attr:`policy_override`\ s during a given method call, it can pass a :class:`PolicySet`\ -derived instance to the object's method. Since the :class:`PolicySet` defines all attributes and methods, none will be referred to the default :attr:`policy` on the object, and the object's object-specific defaults will be ignored. (Note that this is is a very rare use case.) In addition to the base classes already mentioned, the module provides a number of convenience subclasses for commonly used default policy overrides. These classes are subclasses of :class:`Policy`. To use them as default policies, pass them to the constructor of a :class:`PolicySet` class, which will copy the values of the attributes (they have no methods). :class:`Policy` objects can also be composed in the same way; for example, a strict SMTP policy can be created by doing ``SMTP(Strict())`` or ``Strict(SMTP())``. .. class:: Policy(policy_overlay=None, **kw) If an object is passed in as *policy_overlay*, it will be checked for any of the attributes listed for :class:`PolicySet`, and if the attribute exists its value will be used as the value of that attribute for the :class:`Policy` instance returned by the constructor. The valid constructor keyword arguments are any of the attributes listed in :attr:`policy_attributes`, which is any of the attributes documented in :class:`PolicySet`, below. If an attribute occurs both on the *policy_overlay* object and as a keyword argument, the keyword argument takes precedence. .. attribute:: policy_attributes A list of the names of the public API attributes. These are the attributes whose values will be copied from a *policy_overlay* object. .. method:: default_policy(policy) Use *policy* as the source of default policy. Any attributes not defined on the class or in the constructor will be delegated to this object. (This method is used internally to implement the :attr:`policy_override` behavior as well as the behavior when passing a policy to a method. It is exposed as part of the API in case a subclass wants to override it.) .. class:: PolicySet(policy_overlay=None, **kw) If an object is passed in as *policy_overlay*, it will be checked for any of the attributes listed below, and if the attribute exists its value will be used as the value of that attribute for the :class:`PolicySet` instance returned by the constructor. The valid constructor keyword arguments are any of the attributes listed in :attr:`policy_attributes`, which is any of the attributes documented below. If an attribute occurs both on the *policy_overlay* object and as a keyword argument, the keyword argument takes precedence. .. attribute:: policy_attributes A list of the names of the public API attributes. These are the attributes whose values will be copied from a *policy_overlay* object. .. 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:: newline 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 the convenience policy objects for policies that use RFC conformant newlines. Setting it to :attr:`os.linesep` may also be useful. .. attribute:: use_raw_data_if_possible If :const:`True`, then, during serialization, if an object has raw data that raw data will be split into lines via :meth:`~str.splitlines` and emitted. If :const:`False` (the default), the data will be transformed and wrapped as necessary to conform to :attr:`max_line_length`. .. attribute:: must_be_7bit This policy attribute affects only bytes objects. If :const:`True`, data output by serialize is limited to ASCII characters. If :const:`False` (the default), then bytes with the high bit set are allowed in certain contexts (for example, where possible a content transfer encoding of ``8bit`` will be used). .. attribute:: header_indent A string used to prefix all lines after the first when folding message headers. To be RFC compliant this may be composed only of spaces and/or tabs. The default is eight spaces. .. 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. .. attribute:: headers A mapping from case insensitive header names to header classes. Three keys are special: ``__baseclass__`` holds the class that will be used as the base class for all headers, and that will be used as the class for headers whose names do not appear in the registry. The default registry provides :class:`~email.headers.UnstructuredHeader` for this key. ``__stringclass__`` holds the class that will be mixed in to all headers whose source data is of type string. The default registry provides :class:`~email.headers.StringHeaderMixin` for this key. ``__bytesclass__`` holds the class that will be mixed in to all headers whose source data is of type bytes. The default registry provides :class:`~email.headers.BygesHeaderMixin` for this key. .. attribute:: ctes A mapping from :rfc:`2047` content transfer encoding codes to :class:`~email.cte.Coder` classes. The default registry provides mappings for 'q' (quoted printable) and 'b' (base64) CTEs. .. method:: default_policy(policy) This method is a non-operation, and is provided so that a :class:`PolicySet` can be passed as a policy override in a method call. .. method:: handle_defect(obj, defect) *obj* is the object on which the defect is detected. *defect* should be a subclass of :class:`~email.errors.Defect`. If :attr:`raise_on_defect` is :const:`True` *defect* is raised as an error. Otherwise :meth:`register_defect` is called with the object and defect. .. method:: register_defect(obj, defect) *obj* is the object on which the defect is detected. *defect* should be a subclass of :class:`~email.errors.Defect`. The defect is appended to *obj*'s :attr:`defects` attribute. Domain Specific Policies ........................ These are subclasses of :class:`Policy`. :class:`SMTP` Output serialized from a bytes message will conform to the email and SMTP RFCs. The only changed attribute is :attr:`newline`, which is set to '\\r\\n'. :class:`HTTP` Suitable for use when serializing headers for use in HTTP traffic. :attr:`newline` is set to '\\r\\n', and :attr:`max_line_length` is set to :const:`None` (unlimited). :class:`Strict` :attr:`raise_on_defect` is set to :const:`True`. .. rubric:: Footnotes .. [#] For example, the MIME signed message object will set the :attr:`~email.policy.PolicySet.use_raw_data_if_possible` policy attribute to :const:`True`, so that the original data is preserved, as required by :rfc:`1847`, even if the policy otherwise calls for rewrapping lines (as :class:`PolicySet` does by default).