| 1 |
"""This will be the home for the policy that hooks in the new |
| 2 |
code that adds all the email6 features. |
| 3 |
""" |
| 4 |
|
| 5 |
import re |
| 6 |
import sys |
| 7 |
from email._policybase import ( |
| 8 |
Compat32, |
| 9 |
Policy, |
| 10 |
_extend_docstrings, |
| 11 |
compat32, |
| 12 |
validate_header_name |
| 13 |
) |
| 14 |
from email.utils import _has_surrogates |
| 15 |
from email.headerregistry import HeaderRegistry as HeaderRegistry |
| 16 |
from email.contentmanager import raw_data_manager |
| 17 |
from email.message import EmailMessage |
| 18 |
|
| 19 |
__all__ = [ |
| 20 |
'Compat32', |
| 21 |
'compat32', |
| 22 |
'Policy', |
| 23 |
'EmailPolicy', |
| 24 |
'default', |
| 25 |
'strict', |
| 26 |
'SMTP', |
| 27 |
'HTTP', |
| 28 |
] |
| 29 |
|
| 30 |
linesep_splitter = re.compile(r'\n|\r\n?') |
| 31 |
|
| 32 |
@_extend_docstrings |
| 33 |
class EmailPolicy(Policy): |
| 34 |
|
| 35 |
"""+ |
| 36 |
PROVISIONAL |
| 37 |
|
| 38 |
The API extensions enabled by this policy are currently provisional. |
| 39 |
Refer to the documentation for details. |
| 40 |
|
| 41 |
This policy adds new header parsing and folding algorithms. Instead of |
| 42 |
simple strings, headers are custom objects with custom attributes |
| 43 |
depending on the type of the field. The folding algorithm fully |
| 44 |
implements RFCs 2047 and 5322. |
| 45 |
|
| 46 |
In addition to the settable attributes listed above that apply to |
| 47 |
all Policies, this policy adds the following additional attributes: |
| 48 |
|
| 49 |
utf8 -- if False (the default) message headers will be |
| 50 |
serialized as ASCII, using encoded words to encode |
| 51 |
any non-ASCII characters in the source strings. If |
| 52 |
True, the message headers will be serialized using |
| 53 |
utf8 and will not contain encoded words (see RFC |
| 54 |
6532 for more on this serialization format). |
| 55 |
|
| 56 |
refold_source -- if the value for a header in the Message object |
| 57 |
came from the parsing of some source, this attribute |
| 58 |
indicates whether or not a generator should refold |
| 59 |
that value when transforming the message back into |
| 60 |
stream form. The possible values are: |
| 61 |
|
| 62 |
none -- all source values use original folding |
| 63 |
long -- source values that have any line that is |
| 64 |
longer than max_line_length will be |
| 65 |
refolded |
| 66 |
all -- all values are refolded. |
| 67 |
|
| 68 |
The default is 'long'. |
| 69 |
|
| 70 |
header_factory -- a callable that takes two arguments, 'name' and |
| 71 |
'value', where 'name' is a header field name and |
| 72 |
'value' is an unfolded header field value, and |
| 73 |
returns a string-like object that represents that |
| 74 |
header. A default header_factory is provided that |
| 75 |
understands some of the RFC5322 header field types. |
| 76 |
(Currently address fields and date fields have |
| 77 |
special treatment, while all other fields are |
| 78 |
treated as unstructured. This list will be |
| 79 |
completed before the extension is marked stable.) |
| 80 |
|
| 81 |
content_manager -- an object with at least two methods: get_content |
| 82 |
and set_content. When the get_content or |
| 83 |
set_content method of a Message object is called, |
| 84 |
it calls the corresponding method of this object, |
| 85 |
passing it the message object as its first argument, |
| 86 |
and any arguments or keywords that were passed to |
| 87 |
it as additional arguments. The default |
| 88 |
content_manager is |
| 89 |
:data:`~email.contentmanager.raw_data_manager`. |
| 90 |
|
| 91 |
""" |
| 92 |
|
| 93 |
message_factory = EmailMessage |
| 94 |
utf8 = False |
| 95 |
refold_source = 'long' |
| 96 |
header_factory = HeaderRegistry() |
| 97 |
content_manager = raw_data_manager |
| 98 |
|
| 99 |
def __init__(self, **kw): |
| 100 |
# Ensure that each new instance gets a unique header factory |
| 101 |
# (as opposed to clones, which share the factory). |
| 102 |
if 'header_factory' not in kw: |
| 103 |
object.__setattr__(self, 'header_factory', HeaderRegistry()) |
| 104 |
super().__init__(**kw) |
| 105 |
|
| 106 |
def header_max_count(self, name): |
| 107 |
"""+ |
| 108 |
The implementation for this class returns the max_count attribute from |
| 109 |
the specialized header class that would be used to construct a header |
| 110 |
of type 'name'. |
| 111 |
""" |
| 112 |
return self.header_factory[name].max_count |
| 113 |
|
| 114 |
# The logic of the next three methods is chosen such that it is possible to |
| 115 |
# switch a Message object between a Compat32 policy and a policy derived |
| 116 |
# from this class and have the results stay consistent. This allows a |
| 117 |
# Message object constructed with this policy to be passed to a library |
| 118 |
# that only handles Compat32 objects, or to receive such an object and |
| 119 |
# convert it to use the newer style by just changing its policy. It is |
| 120 |
# also chosen because it postpones the relatively expensive full rfc5322 |
| 121 |
# parse until as late as possible when parsing from source, since in many |
| 122 |
# applications only a few headers will actually be inspected. |
| 123 |
|
| 124 |
def header_source_parse(self, sourcelines): |
| 125 |
"""+ |
| 126 |
The name is parsed as everything up to the ':' and returned unmodified. |
| 127 |
The value is determined by stripping leading whitespace off the |
| 128 |
remainder of the first line joined with all subsequent lines, and |
| 129 |
stripping any trailing carriage return or linefeed characters. (This |
| 130 |
is the same as Compat32). |
| 131 |
|
| 132 |
""" |
| 133 |
name, value = sourcelines[0].split(':', 1) |
| 134 |
value = ''.join((value, *sourcelines[1:])).lstrip(' \t\r\n') |
| 135 |
return (name, value.rstrip('\r\n')) |
| 136 |
|
| 137 |
def header_store_parse(self, name, value): |
| 138 |
"""+ |
| 139 |
The name is returned unchanged. If the input value has a 'name' |
| 140 |
attribute and it matches the name ignoring case, the value is returned |
| 141 |
unchanged. Otherwise the name and value are passed to header_factory |
| 142 |
method, and the resulting custom header object is returned as the |
| 143 |
value. In this case a ValueError is raised if the input value contains |
| 144 |
CR or LF characters. |
| 145 |
|
| 146 |
""" |
| 147 |
validate_header_name(name) |
| 148 |
if hasattr(value, 'name') and value.name.lower() == name.lower(): |
| 149 |
return (name, value) |
| 150 |
if isinstance(value, str) and len(value.splitlines())>1: |
| 151 |
# XXX this error message isn't quite right when we use splitlines |
| 152 |
# (see issue 22233), but I'm not sure what should happen here. |
| 153 |
raise ValueError("Header values may not contain linefeed " |
| 154 |
"or carriage return characters") |
| 155 |
return (name, self.header_factory(name, value)) |
| 156 |
|
| 157 |
def header_fetch_parse(self, name, value): |
| 158 |
"""+ |
| 159 |
If the value has a 'name' attribute, it is returned to unmodified. |
| 160 |
Otherwise the name and the value with any linesep characters removed |
| 161 |
are passed to the header_factory method, and the resulting custom |
| 162 |
header object is returned. Any surrogateescaped bytes get turned |
| 163 |
into the unicode unknown-character glyph. |
| 164 |
|
| 165 |
""" |
| 166 |
if hasattr(value, 'name'): |
| 167 |
return value |
| 168 |
# We can't use splitlines here because it splits on more than \r and \n. |
| 169 |
value = ''.join(linesep_splitter.split(value)) |
| 170 |
return self.header_factory(name, value) |
| 171 |
|
| 172 |
def fold(self, name, value): |
| 173 |
"""+ |
| 174 |
Header folding is controlled by the refold_source policy setting. A |
| 175 |
value is considered to be a 'source value' if and only if it does not |
| 176 |
have a 'name' attribute (having a 'name' attribute means it is a header |
| 177 |
object of some sort). If a source value needs to be refolded according |
| 178 |
to the policy, it is converted into a custom header object by passing |
| 179 |
the name and the value with any linesep characters removed to the |
| 180 |
header_factory method. Folding of a custom header object is done by |
| 181 |
calling its fold method with the current policy. |
| 182 |
|
| 183 |
Source values are split into lines using splitlines. If the value is |
| 184 |
not to be refolded, the lines are rejoined using the linesep from the |
| 185 |
policy and returned. The exception is lines containing non-ascii |
| 186 |
binary data. In that case the value is refolded regardless of the |
| 187 |
refold_source setting, which causes the binary data to be CTE encoded |
| 188 |
using the unknown-8bit charset. |
| 189 |
|
| 190 |
""" |
| 191 |
return self._fold(name, value, refold_binary=True) |
| 192 |
|
| 193 |
def fold_binary(self, name, value): |
| 194 |
"""+ |
| 195 |
The same as fold if cte_type is 7bit, except that the returned value is |
| 196 |
bytes. |
| 197 |
|
| 198 |
If cte_type is 8bit, non-ASCII binary data is converted back into |
| 199 |
bytes. Headers with binary data are not refolded, regardless of the |
| 200 |
refold_header setting, since there is no way to know whether the binary |
| 201 |
data consists of single byte characters or multibyte characters. |
| 202 |
|
| 203 |
If utf8 is true, headers are encoded to utf8, otherwise to ascii with |
| 204 |
non-ASCII unicode rendered as encoded words. |
| 205 |
|
| 206 |
""" |
| 207 |
folded = self._fold(name, value, refold_binary=self.cte_type=='7bit') |
| 208 |
charset = 'utf8' if self.utf8 else 'ascii' |
| 209 |
return folded.encode(charset, 'surrogateescape') |
| 210 |
|
| 211 |
def _fold(self, name, value, refold_binary=False): |
| 212 |
if hasattr(value, 'name'): |
| 213 |
return value.fold(policy=self) |
| 214 |
maxlen = self.max_line_length if self.max_line_length else sys.maxsize |
| 215 |
# We can't use splitlines here because it splits on more than \r and \n. |
| 216 |
lines = linesep_splitter.split(value) |
| 217 |
refold = (self.refold_source == 'all' or |
| 218 |
self.refold_source == 'long' and |
| 219 |
(lines and len(lines[0])+len(name)+2 > maxlen or |
| 220 |
any(len(x) > maxlen for x in lines[1:]))) |
| 221 |
|
| 222 |
if not refold: |
| 223 |
if not self.utf8: |
| 224 |
refold = not value.isascii() |
| 225 |
elif refold_binary: |
| 226 |
refold = _has_surrogates(value) |
| 227 |
if refold: |
| 228 |
return self.header_factory(name, ''.join(lines)).fold(policy=self) |
| 229 |
|
| 230 |
return name + ': ' + self.linesep.join(lines) + self.linesep |
| 231 |
|
| 232 |
|
| 233 |
default = EmailPolicy() |
| 234 |
# Make the default policy use the class default header_factory |
| 235 |
del default.header_factory |
| 236 |
strict = default.clone(raise_on_defect=True) |
| 237 |
SMTP = default.clone(linesep='\r\n') |
| 238 |
HTTP = default.clone(linesep='\r\n', max_line_length=None) |
| 239 |
SMTPUTF8 = SMTP.clone(utf8=True) |