New in version 3.3.
The 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 Policy object encapsulates a set of attributes and methods that control the behavior of various components of the email package during use. 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 policy module also provides some pre-created Policy instances. In addition to a default instance, there are instances tailored for certain applications. For example there is an SMTP Policy with defaults appropriate for generating output to be sent to an SMTP server. These are listed below <Policy Instances>.
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 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 Policy can be specified when parsing a message to create a Message, and again when turning the Message into some other representation. While often a program will use the same 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()
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 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 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
The valid constructor keyword arguments are any of the attributes listed below.
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 None indicates that no line wrapping should be done at all.
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 os.linesep may also be useful.
If True, data output by a bytes generator is limited to ASCII characters. If 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.
If True, any defects encountered will be raised as errors. If False (the default), defects will be passed to the register_defect() method.
Policy object also have the following methods:
obj is the object on which to register the defect. defect should be an instance of a subclass of Defect. If raise_on_defect is True the defect is raised as an exception. Otherwise obj and defect are passed to 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.
obj is the object on which to register the defect. defect should be a subclass of 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.
The following instances of Policy provide defaults suitable for specific common application domains.
Output serialized from a message will conform to the email and SMTP RFCs. The only changed attribute is linesep, which is set to \r\n.