Python code coverage for Lib/email/_policybase.py

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