Debian Codegraph @

Lib/email/_policybase.py

raw
1 """Policy framework for the email package.
2
3 Allows fine grained feature control of how the package parses and emits data.
4 """
5
6 import abc
7 import re
8 from email import header
9 from email import charset as _charset
10 from email.utils import _has_surrogates
11
12 __all__ = [
13 'Policy',
14 'Compat32',
15 'compat32',
16 ]
17
18 # validation regex from RFC 5322, equivalent to pattern re.compile("[!-9;-~]+$")
19 valid_header_name_re = re.compile("[\041-\071\073-\176]+$")
20
21 def validate_header_name(name):
22 # Validate header name according to RFC 5322
23 if not valid_header_name_re.match(name):
24 raise ValueError(
25 f"Header field name contains invalid characters: {name!r}")
26
27 class _PolicyBase:
28
29 """Policy Object basic framework.
30
31 This class is useless unless subclassed. A subclass should define
32 class attributes with defaults for any values that are to be
33 managed by the Policy object. The constructor will then allow
34 non-default values to be set for these attributes at instance
35 creation time. The instance will be callable, taking these same
36 attributes keyword arguments, and returning a new instance
37 identical to the called instance except for those values changed
38 by the keyword arguments. Instances may be added, yielding new
39 instances with any non-default values from the right hand
40 operand overriding those in the left hand operand. That is,
41
42 A + B == A(<non-default values of B>)
43
44 The repr of an instance can be used to reconstruct the object
45 if and only if the repr of the values can be used to reconstruct
46 those values.
47
48 """
49
50 def __init__(self, **kw):
51 """Create new Policy, possibly overriding some defaults.
52
53 See class docstring for a list of overridable attributes.
54
55 """
56 for name, value in kw.items():
57 if hasattr(self, name):
58 super(_PolicyBase,self).__setattr__(name, value)
59 else:
60 raise TypeError(
61 "{!r} is an invalid keyword argument for {}".format(
62 name, self.__class__.__name__))
63
64 def __repr__(self):
65 args = [ "{}={!r}".format(name, value)
66 for name, value in self.__dict__.items() ]
67 return "{}({})".format(self.__class__.__name__, ', '.join(args))
68
69 def clone(self, **kw):
70 """Return a new instance with specified attributes changed.
71
72 The new instance has the same attribute values as the current object,
73 except for the changes passed in as keyword arguments.
74
75 """
76 newpolicy = self.__class__.__new__(self.__class__)
77 for attr, value in self.__dict__.items():
78 object.__setattr__(newpolicy, attr, value)
79 for attr, value in kw.items():
80 if not hasattr(self, attr):
81 raise TypeError(
82 "{!r} is an invalid keyword argument for {}".format(
83 attr, self.__class__.__name__))
84 object.__setattr__(newpolicy, attr, value)
85 return newpolicy
86
87 def __setattr__(self, name, value):
88 if hasattr(self, name):
89 msg = "{!r} object attribute {!r} is read-only"
90 else:
91 msg = "{!r} object has no attribute {!r}"
92 raise AttributeError(msg.format(self.__class__.__name__, name))
93
94 def __add__(self, other):
95 """Non-default values from right operand override those from left.
96
97 The object returned is a new instance of the subclass.
98
99 """
100 return self.clone(**other.__dict__)
101
102
103 def _append_doc(doc, added_doc):
104 doc = doc.rsplit('\n', 1)[0]
105 added_doc = added_doc.split('\n', 1)[1]
106 return doc + '\n' + added_doc
107
108 def _extend_docstrings(cls):
109 if cls.__doc__ and cls.__doc__.startswith('+'):
110 cls.__doc__ = _append_doc(cls.__bases__[0].__doc__, cls.__doc__)
111 for name, attr in cls.__dict__.items():
112 if attr.__doc__ and attr.__doc__.startswith('+'):
113 for c in (c for base in cls.__bases__ for c in base.mro()):
114 doc = getattr(getattr(c, name), '__doc__')
115 if doc:
116 attr.__doc__ = _append_doc(doc, attr.__doc__)
117 break
118 return cls
119
120
121 class Policy(_PolicyBase, metaclass=abc.ABCMeta):
122
123 r"""Controls for how messages are interpreted and formatted.
124
125 Most of the classes and many of the methods in the email package accept
126 Policy objects as parameters. A Policy object contains a set of values and
127 functions that control how input is interpreted and how output is rendered.
128 For example, the parameter 'raise_on_defect' controls whether or not an RFC
129 violation results in an error being raised or not, while 'max_line_length'
130 controls the maximum length of output lines when a Message is serialized.
131
132 Any valid attribute may be overridden when a Policy is created by passing
133 it as a keyword argument to the constructor. Policy objects are immutable,
134 but a new Policy object can be created with only certain values changed by
135 calling the Policy instance with keyword arguments. Policy objects can
136 also be added, producing a new Policy object in which the non-default
137 attributes set in the right hand operand overwrite those specified in the
138 left operand.
139
140 Settable attributes:
141
142 raise_on_defect -- If true, then defects should be raised as errors.
143 Default: False.
144
145 linesep -- string containing the value to use as separation
146 between output lines. Default '\n'.
147
148 cte_type -- Type of allowed content transfer encodings
149
150 7bit -- ASCII only
151 8bit -- Content-Transfer-Encoding: 8bit is allowed
152
153 Default: 8bit. Also controls the disposition of
154 (RFC invalid) binary data in headers; see the
155 documentation of the binary_fold method.
156
157 max_line_length -- maximum length of lines, excluding 'linesep',
158 during serialization. None or 0 means no line
159 wrapping is done. Default is 78.
160
161 mangle_from_ -- a flag that, when True escapes From_ lines in the
162 body of the message by putting a '>' in front of
163 them. This is used when the message is being
164 serialized by a generator. Default: False.
165
166 message_factory -- the class to use to create new message objects.
167 If the value is None, the default is Message.
168
169 verify_generated_headers
170 -- if true, the generator verifies that each header
171 they are properly folded, so that a parser won't
172 treat it as multiple headers, start-of-body, or
173 part of another header.
174 This is a check against custom Header & fold()
175 implementations.
176 """
177
178 raise_on_defect = False
179 linesep = '\n'
180 cte_type = '8bit'
181 max_line_length = 78
182 mangle_from_ = False
183 message_factory = None
184 verify_generated_headers = True
185
186 def handle_defect(self, obj, defect):
187 """Based on policy, either raise defect or call register_defect.
188
189 handle_defect(obj, defect)
190
191 defect should be a Defect subclass, but in any case must be an
192 Exception subclass. obj is the object on which the defect should be
193 registered if it is not raised. If the raise_on_defect is True, the
194 defect is raised as an error, otherwise the object and the defect are
195 passed to register_defect.
196
197 This method is intended to be called by parsers that discover defects.
198 The email package parsers always call it with Defect instances.
199
200 """
201 if self.raise_on_defect:
202 raise defect
203 self.register_defect(obj, defect)
204
205 def register_defect(self, obj, defect):
206 """Record 'defect' on 'obj'.
207
208 Called by handle_defect if raise_on_defect is False. This method is
209 part of the Policy API so that Policy subclasses can implement custom
210 defect handling. The default implementation calls the append method of
211 the defects attribute of obj. The objects used by the email package by
212 default that get passed to this method will always have a defects
213 attribute with an append method.
214
215 """
216 obj.defects.append(defect)
217
218 def header_max_count(self, name):
219 """Return the maximum allowed number of headers named 'name'.
220
221 Called when a header is added to a Message object. If the returned
222 value is not 0 or None, and there are already a number of headers with
223 the name 'name' equal to the value returned, a ValueError is raised.
224
225 Because the default behavior of Message's __setitem__ is to append the
226 value to the list of headers, it is easy to create duplicate headers
227 without realizing it. This method allows certain headers to be limited
228 in the number of instances of that header that may be added to a
229 Message programmatically. (The limit is not observed by the parser,
230 which will faithfully produce as many headers as exist in the message
231 being parsed.)
232
233 The default implementation returns None for all header names.
234 """
235 return None
236
237 @abc.abstractmethod
238 def header_source_parse(self, sourcelines):
239 """Given a list of linesep terminated strings constituting the lines of
240 a single header, return the (name, value) tuple that should be stored
241 in the model. The input lines should retain their terminating linesep
242 characters. The lines passed in by the email package may contain
243 surrogateescaped binary data.
244 """
245 raise NotImplementedError
246
247 @abc.abstractmethod
248 def header_store_parse(self, name, value):
249 """Given the header name and the value provided by the application
250 program, return the (name, value) that should be stored in the model.
251 """
252 raise NotImplementedError
253
254 @abc.abstractmethod
255 def header_fetch_parse(self, name, value):
256 """Given the header name and the value from the model, return the value
257 to be returned to the application program that is requesting that
258 header. The value passed in by the email package may contain
259 surrogateescaped binary data if the lines were parsed by a BytesParser.
260 The returned value should not contain any surrogateescaped data.
261
262 """
263 raise NotImplementedError
264
265 @abc.abstractmethod
266 def fold(self, name, value):
267 """Given the header name and the value from the model, return a string
268 containing linesep characters that implement the folding of the header
269 according to the policy controls. The value passed in by the email
270 package may contain surrogateescaped binary data if the lines were
271 parsed by a BytesParser. The returned value should not contain any
272 surrogateescaped data.
273
274 """
275 raise NotImplementedError
276
277 @abc.abstractmethod
278 def fold_binary(self, name, value):
279 """Given the header name and the value from the model, return binary
280 data containing linesep characters that implement the folding of the
281 header according to the policy controls. The value passed in by the
282 email package may contain surrogateescaped binary data.
283
284 """
285 raise NotImplementedError
286
287
288 @_extend_docstrings
289 class Compat32(Policy):
290
291 """+
292 This particular policy is the backward compatibility Policy. It
293 replicates the behavior of the email package version 5.1.
294 """
295
296 mangle_from_ = True
297
298 def _sanitize_header(self, name, value):
299 # If the header value contains surrogates, return a Header using
300 # the unknown-8bit charset to encode the bytes as encoded words.
301 if not isinstance(value, str):
302 # Assume it is already a header object
303 return value
304 if _has_surrogates(value):
305 return header.Header(value, charset=_charset.UNKNOWN8BIT,
306 header_name=name)
307 else:
308 return value
309
310 def header_source_parse(self, sourcelines):
311 """+
312 The name is parsed as everything up to the ':' and returned unmodified.
313 The value is determined by stripping leading whitespace off the
314 remainder of the first line joined with all subsequent lines, and
315 stripping any trailing carriage return or linefeed characters.
316
317 """
318 name, value = sourcelines[0].split(':', 1)
319 value = ''.join((value, *sourcelines[1:])).lstrip(' \t\r\n')
320 return (name, value.rstrip('\r\n'))
321
322 def header_store_parse(self, name, value):
323 """+
324 The name and value are returned unmodified.
325 """
326 validate_header_name(name)
327 return (name, value)
328
329 def header_fetch_parse(self, name, value):
330 """+
331 If the value contains binary data, it is converted into a Header object
332 using the unknown-8bit charset. Otherwise it is returned unmodified.
333 """
334 return self._sanitize_header(name, value)
335
336 def fold(self, name, value):
337 """+
338 Headers are folded using the Header folding algorithm, which preserves
339 existing line breaks in the value, and wraps each resulting line to the
340 max_line_length. Non-ASCII binary data are CTE encoded using the
341 unknown-8bit charset.
342
343 """
344 return self._fold(name, value, sanitize=True)
345
346 def fold_binary(self, name, value):
347 """+
348 Headers are folded using the Header folding algorithm, which preserves
349 existing line breaks in the value, and wraps each resulting line to the
350 max_line_length. If cte_type is 7bit, non-ascii binary data is CTE
351 encoded using the unknown-8bit charset. Otherwise the original source
352 header is used, with its existing line breaks and/or binary data.
353
354 """
355 folded = self._fold(name, value, sanitize=self.cte_type=='7bit')
356 return folded.encode('ascii', 'surrogateescape')
357
358 def _fold(self, name, value, sanitize):
359 parts = []
360 parts.append('%s: ' % name)
361 if isinstance(value, str):
362 if _has_surrogates(value):
363 if sanitize:
364 h = header.Header(value,
365 charset=_charset.UNKNOWN8BIT,
366 header_name=name)
367 else:
368 # If we have raw 8bit data in a byte string, we have no idea
369 # what the encoding is. There is no safe way to split this
370 # string. If it's ascii-subset, then we could do a normal
371 # ascii split, but if it's multibyte then we could break the
372 # string. There's no way to know so the least harm seems to
373 # be to not split the string and risk it being too long.
374 parts.append(value)
375 h = None
376 else:
377 h = header.Header(value, header_name=name)
378 else:
379 # Assume it is a Header-like object.
380 h = value
381 if h is not None:
382 # The Header class interprets a value of None for maxlinelen as the
383 # default value of 78, as recommended by RFC 5322 section 2.1.1.
384 maxlinelen = 0
385 if self.max_line_length is not None:
386 maxlinelen = self.max_line_length
387 parts.append(h.encode(linesep=self.linesep, maxlinelen=maxlinelen))
388 parts.append(self.linesep)
389 return ''.join(parts)
390
391
392 compat32 = Compat32()