class email.policy.Policy(**kw)
This is the abstract base class for all policy classes. It provides default implementations for a couple of trivial methods, as well as the implementation of the immutability property, the clone()
method, and the constructor semantics.
The constructor of a policy class can be passed various keyword arguments. The arguments that may be specified are any non-method properties on this class, plus any additional non-method properties on the concrete class. A value specified in the constructor will override the default value for the corresponding attribute.
This class defines the following properties, and thus values for the following may be passed in the constructor of any policy class:
-
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
orNone
indicates that no line wrapping should be done at all.
-
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.
-
cte_type
-
Controls the type of Content Transfer Encodings that may be or are required to be used. The possible values are:
7bit
all data must be “7 bit clean” (ASCII-only). This means that where necessary data will be encoded using either quoted-printable or base64 encoding. 8bit
data is not constrained to be 7 bit clean. Data in headers is still required to be ASCII-only and so will be encoded (see ‘binary_fold’ below for an exception), but body parts may use the 8bit
CTE.A
cte_type
value of8bit
only works withBytesGenerator
, notGenerator
, because strings cannot contain binary data. If aGenerator
is operating under a policy that specifiescte_type=8bit
, it will act as ifcte_type
is7bit
.
-
raise_on_defect
-
If
True
, any defects encountered will be raised as errors. IfFalse
(the default), defects will be passed to theregister_defect()
method.
-
mangle_from_
-
If
True
, lines starting with “From “ in the body are escaped by putting a>
in front of them. This parameter is used when the message is being serialized by a generator. Default:False
.New in version 3.5: The mangle_from_ parameter.
The following Policy
method is intended to be called by code using the email library to create policy instances with custom settings:
-
clone(**kw)
-
Return a new
Policy
instance whose attributes have the same values as the current instance, except where those attributes are given new values by the keyword arguments.
The remaining Policy
methods are called by the email package code, and are not intended to be called by an application using the email package. A custom policy must implement all of these methods.
-
handle_defect(obj, defect)
-
Handle a defect found on obj. When the email package calls this method, defect will always be a subclass of
Defect
.The default implementation checks the
raise_on_defect
flag. If it isTrue
, defect is raised as an exception. If it isFalse
(the default), obj and defect are passed toregister_defect()
.
-
register_defect(obj, defect)
-
Register a defect on obj. In the email package, defect will always be a subclass of
Defect
.The default implementation calls the
append
method of thedefects
attribute of obj. When the email package callshandle_defect
, obj will normally have adefects
attribute that has anappend
method. Custom object types used with the email package (for example, customMessage
objects) should also provide such an attribute, otherwise defects in parsed messages will raise unexpected errors.
-
header_max_count(name)
-
Return the maximum allowed number of headers named name.
Called when a header is added to a
Message
object. If the returned value is not0
orNone
, and there are already a number of headers with the name name equal to the value returned, aValueError
is raised.Because the default behavior of
Message.__setitem__
is to append the value to the list of headers, it is easy to create duplicate headers without realizing it. This method allows certain headers to be limited in the number of instances of that header that may be added to aMessage
programmatically. (The limit is not observed by the parser, which will faithfully produce as many headers as exist in the message being parsed.)The default implementation returns
None
for all header names.
-
header_source_parse(sourcelines)
-
The email package calls this method with a list of strings, each string ending with the line separation characters found in the source being parsed. The first line includes the field header name and separator. All whitespace in the source is preserved. The method should return the
(name, value)
tuple that is to be stored in theMessage
to represent the parsed header.If an implementation wishes to retain compatibility with the existing email package policies, name should be the case preserved name (all characters up to the ‘
:
‘ separator), while value should be the unfolded value (all line separator characters removed, but whitespace kept intact), stripped of leading whitespace.sourcelines may contain surrogateescaped binary data.
There is no default implementation
-
header_store_parse(name, value)
-
The email package calls this method with the name and value provided by the application program when the application program is modifying a
Message
programmatically (as opposed to aMessage
created by a parser). The method should return the(name, value)
tuple that is to be stored in theMessage
to represent the header.If an implementation wishes to retain compatibility with the existing email package policies, the name and value should be strings or string subclasses that do not change the content of the passed in arguments.
There is no default implementation
-
header_fetch_parse(name, value)
-
The email package calls this method with the name and value currently stored in the
Message
when that header is requested by the application program, and whatever the method returns is what is passed back to the application as the value of the header being retrieved. Note that there may be more than one header with the same name stored in theMessage
; the method is passed the specific name and value of the header destined to be returned to the application.value may contain surrogateescaped binary data. There should be no surrogateescaped binary data in the value returned by the method.
There is no default implementation
-
fold(name, value)
-
The email package calls this method with the name and value currently stored in the
Message
for a given header. The method should return a string that represents that header “folded” correctly (according to the policy settings) by composing the name with the value and insertinglinesep
characters at the appropriate places. See RFC 5322 for a discussion of the rules for folding email headers.value may contain surrogateescaped binary data. There should be no surrogateescaped binary data in the string returned by the method.
-
fold_binary(name, value)
-
The same as
fold()
, except that the returned value should be a bytes object rather than a string.value may contain surrogateescaped binary data. These could be converted back into binary data in the returned bytes object.
Please login to continue.