policy framework for the email package allows fine grained feature control of how the package parses and emits data policy object basic framework this class is useless unless subclassed a subclass should define class attributes with defaults for any values that are to be managed by the policy object the constructor will then allow nondefault values to be set for these attributes at instance creation time the instance will be callable taking these same attributes keyword arguments and returning a new instance identical to the called instance except for those values changed by the keyword arguments instances may be added yielding new instances with any nondefault values from the right hand operand overriding those in the left hand operand that is a b anondefault values of b the repr of an instance can be used to reconstruct the object if and only if the repr of the values can be used to reconstruct those values create new policy possibly overriding some defaults see class docstring for a list of overridable attributes return a new instance with specified attributes changed the new instance has the same attribute values as the current object except for the changes passed in as keyword arguments nondefault values from right operand override those from left the object returned is a new instance of the subclass raiseondefect false linesep n ctetype 8bit maxlinelength 78 manglefrom false messagefactory none def handledefectself obj defect if self raiseondefect raise defect self registerdefectobj defect def registerdefectself obj defect obj defects appenddefect def headermaxcountself name return none abc abstractmethod def headersourceparseself sourcelines raise notimplementederror abc abstractmethod def headerstoreparseself name value raise notimplementederror abc abstractmethod def headerfetchparseself name value raise notimplementederror abc abstractmethod def foldself name value raise notimplementederror abc abstractmethod def foldbinaryself name value raise notimplementederror extenddocstrings class compat32policy manglefrom true def sanitizeheaderself name value if the header value contains surrogates return a header using the unknown8bit charset to encode the bytes as encoded words if not isinstancevalue str assume it is already a header object return value if hassurrogatesvalue return header headervalue charsetcharset unknown8bit headernamename else return value def headersourceparseself sourcelines name value sourcelines0 split 1 value value lstrip t joinsourcelines1 return name value rstrip rn def headerstoreparseself name value return name value def headerfetchparseself name value return self sanitizeheadername value def foldself name value return self foldname value sanitizetrue def foldbinaryself name value folded self foldname value sanitizeself ctetype 7bit return folded encode ascii surrogateescape def foldself name value sanitize parts parts append s name if isinstancevalue str if hassurrogatesvalue if sanitize h header headervalue charsetcharset unknown8bit headernamename else if we have raw 8bit data in a byte string we have no idea what the encoding is there is no safe way to split this string if it s asciisubset then we could do a normal ascii split but if it s multibyte then we could break the string there s no way to know so the least harm seems to be to not split the string and risk it being too long parts appendvalue h none else h header headervalue headernamename else assume it is a headerlike object h value if h is not none the header class interprets a value of none for maxlinelen as the default value of 78 as recommended by rfc 2822 maxlinelen 0 if self maxlinelength is not none maxlinelen self maxlinelength parts appendh encodelinesepself linesep maxlinelenmaxlinelen parts appendself linesep return joinparts compat32 compat32 policy object basic framework this class is useless unless subclassed a subclass should define class attributes with defaults for any values that are to be managed by the policy object the constructor will then allow non default values to be set for these attributes at instance creation time the instance will be callable taking these same attributes keyword arguments and returning a new instance identical to the called instance except for those values changed by the keyword arguments instances may be added yielding new instances with any non default values from the right hand operand overriding those in the left hand operand that is a b a non default values of b the repr of an instance can be used to reconstruct the object if and only if the repr of the values can be used to reconstruct those values create new policy possibly overriding some defaults see class docstring for a list of overridable attributes return a new instance with specified attributes changed the new instance has the same attribute values as the current object except for the changes passed in as keyword arguments non default values from right operand override those from left the object returned is a new instance of the subclass controls for how messages are interpreted and formatted most of the classes and many of the methods in the email package accept policy objects as parameters a policy object contains a set of values and functions that control how input is interpreted and how output is rendered for example the parameter raise_on_defect controls whether or not an rfc violation results in an error being raised or not while max_line_length controls the maximum length of output lines when a message is serialized any valid attribute may be overridden when a policy is passing it as a keyword argument to the constructor policy objects are immutable but a new policy object can be created with only certain values changed by calling the policy instance with keyword arguments policy objects can also be added producing a new policy object in which the non default attributes set in the right hand operand overwrite those specified in the left operand settable attributes raise_on_defect if true then defects should be raised as errors default false linesep string containing the value to use as separation between output lines default n cte_type type of allowed content transfer encodings 7bit ascii only 8bit content transfer encoding 8bit is allowed default 8bit also controls the disposition of rfc invalid binary data in headers see the documentation of the binary_fold method max_line_length maximum length of lines excluding linesep during serialization none or 0 means no line wrapping is done default is 78 mangle_from_ a flag that when true escapes from_ lines in the body of the message by putting a in front of them this is used when the message is being serialized by a generator default true message_factory the class to use to create new message objects if the value is none the default is message based on policy either raise defect or call register_defect handle_defect obj defect defect should be a defect subclass but in any case must be an exception subclass obj is the object on which the defect should be registered if it is not raised if the raise_on_defect is true the defect is raised as an error otherwise the object and the defect are passed to register_defect this method is intended to be called by parsers that discover defects the email package parsers always call it with defect instances record defect on obj called by handle_defect if raise_on_defect is false this method is part of the policy api so that policy subclasses can implement custom defect handling the default implementation calls the append method of the defects attribute of obj the objects used by the email package by default that get passed to this method will always have a defects attribute with an append method return the maximum allowed number of headers named name called when a header is added to a message object if the returned value is not 0 or none and there are already a number of headers with the name name equal to the value returned a valueerror is raised because the default behavior of message s __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 a message 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 given a list of linesep terminated strings constituting the lines of a single header return the name value tuple that should be stored in the model the input lines should retain their terminating linesep characters the lines passed in by the email package may contain surrogateescaped binary data given the header name and the value provided by the application program return the name value that should be stored in the model given the header name and the value from the model return the value to be returned to the application program that is requesting that header the value passed in by the email package may contain surrogateescaped binary data if the lines were parsed by a bytesparser the returned value should not contain any surrogateescaped data given the header name and the value from the model return a string containing linesep characters that implement the folding of the header according to the policy controls the value passed in by the email package may contain surrogateescaped binary data if the lines were parsed by a bytesparser the returned value should not contain any surrogateescaped data given the header name and the value from the model return binary data containing linesep characters that implement the folding of the header according to the policy controls the value passed in by the email package may contain surrogateescaped binary data this particular policy is the backward compatibility policy it replicates the behavior of the email package version 5 1 if the header value contains surrogates return a header using the unknown 8bit charset to encode the bytes as encoded words assume it is already a header object the name is parsed as everything up to the and returned unmodified the value is determined by stripping leading whitespace off the remainder of the first line joining all subsequent lines together and stripping any trailing carriage return or linefeed characters the name and value are returned unmodified if the value contains binary data it is converted into a header object using the unknown 8bit charset otherwise it is returned unmodified headers are folded using the header folding algorithm which preserves existing line breaks in the value and wraps each resulting line to the max_line_length non ascii binary data are cte encoded using the unknown 8bit charset headers are folded using the header folding algorithm which preserves existing line breaks in the value and wraps each resulting line to the max_line_length if cte_type is 7bit non ascii binary data is cte encoded using the unknown 8bit charset otherwise the original source header is used with its existing line breaks and or binary data if we have raw 8bit data in a byte string we have no idea what the encoding is there is no safe way to split this string if it s ascii subset then we could do a normal ascii split but if it s multibyte then we could break the string there s no way to know so the least harm seems to be to not split the string and risk it being too long assume it is a header like object the header class interprets a value of none for maxlinelen as the default value of 78 as recommended by rfc 2822
import abc
from email import header
from email import charset as _charset
from email.utils import _has_surrogates

__all__ = [
    'Policy',
    'Compat32',
    'compat32',
    ]


class _PolicyBase:

    

    def __init__(self, **kw):
        
        for name, value in kw.items():
            if hasattr(self, name):
                super(_PolicyBase,self).__setattr__(name, value)
            else:
                raise TypeError(
                    "{!r} is an invalid keyword argument for {}".format(
                        name, self.__class__.__name__))

    def __repr__(self):
        args = [ "{}={!r}".format(name, value)
                 for name, value in self.__dict__.items() ]
        return "{}({})".format(self.__class__.__name__, ', '.join(args))

    def clone(self, **kw):
        
        newpolicy = self.__class__.__new__(self.__class__)
        for attr, value in self.__dict__.items():
            object.__setattr__(newpolicy, attr, value)
        for attr, value in kw.items():
            if not hasattr(self, attr):
                raise TypeError(
                    "{!r} is an invalid keyword argument for {}".format(
                        attr, self.__class__.__name__))
            object.__setattr__(newpolicy, attr, value)
        return newpolicy

    def __setattr__(self, name, value):
        if hasattr(self, name):
            msg = "{!r} object attribute {!r} is read-only"
        else:
            msg = "{!r} object has no attribute {!r}"
        raise AttributeError(msg.format(self.__class__.__name__, name))

    def __add__(self, other):
        
        return self.clone(**other.__dict__)


def _append_doc(doc, added_doc):
    doc = doc.rsplit('\n', 1)[0]
    added_doc = added_doc.split('\n', 1)[1]
    return doc + '\n' + added_doc

def _extend_docstrings(cls):
    if cls.__doc__ and cls.__doc__.startswith('+'):
        cls.__doc__ = _append_doc(cls.__bases__[0].__doc__, cls.__doc__)
    for name, attr in cls.__dict__.items():
        if attr.__doc__ and attr.__doc__.startswith('+'):
            for c in (c for base in cls.__bases__ for c in base.mro()):
                doc = getattr(getattr(c, name), '__doc__')
                if doc:
                    attr.__doc__ = _append_doc(doc, attr.__doc__)
                    break
    return cls


class Policy(_PolicyBase, metaclass=abc.ABCMeta):

    r

    raise_on_defect = False
    linesep = '\n'
    cte_type = '8bit'
    max_line_length = 78
    mangle_from_ = False
    message_factory = None

    def handle_defect(self, obj, defect):
        
        if self.raise_on_defect:
            raise defect
        self.register_defect(obj, defect)

    def register_defect(self, obj, defect):
        
        obj.defects.append(defect)

    def header_max_count(self, name):
        
        return None

    @abc.abstractmethod
    def header_source_parse(self, sourcelines):
        
        raise NotImplementedError

    @abc.abstractmethod
    def header_store_parse(self, name, value):
        
        raise NotImplementedError

    @abc.abstractmethod
    def header_fetch_parse(self, name, value):
        
        raise NotImplementedError

    @abc.abstractmethod
    def fold(self, name, value):
        
        raise NotImplementedError

    @abc.abstractmethod
    def fold_binary(self, name, value):
        
        raise NotImplementedError


@_extend_docstrings
class Compat32(Policy):

    

    mangle_from_ = True

    def _sanitize_header(self, name, value):
        
        
        if not isinstance(value, str):
            
            return value
        if _has_surrogates(value):
            return header.Header(value, charset=_charset.UNKNOWN8BIT,
                                 header_name=name)
        else:
            return value

    def header_source_parse(self, sourcelines):
        
        name, value = sourcelines[0].split(':', 1)
        value = value.lstrip(' \t') + ''.join(sourcelines[1:])
        return (name, value.rstrip('\r\n'))

    def header_store_parse(self, name, value):
        
        return (name, value)

    def header_fetch_parse(self, name, value):
        
        return self._sanitize_header(name, value)

    def fold(self, name, value):
        
        return self._fold(name, value, sanitize=True)

    def fold_binary(self, name, value):
        
        folded = self._fold(name, value, sanitize=self.cte_type=='7bit')
        return folded.encode('ascii', 'surrogateescape')

    def _fold(self, name, value, sanitize):
        parts = []
        parts.append('%s: ' % name)
        if isinstance(value, str):
            if _has_surrogates(value):
                if sanitize:
                    h = header.Header(value,
                                      charset=_charset.UNKNOWN8BIT,
                                      header_name=name)
                else:
                    
                    
                    
                    
                    
                    
                    parts.append(value)
                    h = None
            else:
                h = header.Header(value, header_name=name)
        else:
            
            h = value
        if h is not None:
            
            
            maxlinelen = 0
            if self.max_line_length is not None:
                maxlinelen = self.max_line_length
            parts.append(h.encode(linesep=self.linesep, maxlinelen=maxlinelen))
        parts.append(self.linesep)
        return ''.join(parts)


compat32 = Compat32()