Python code coverage for Lib/email/headerregistry.py

#	count	content
1	n/a	"""Representing and manipulating email headers via custom objects.
2	n/a
3	n/a	This module provides an implementation of the HeaderRegistry API.
4	n/a	The implementation is designed to flexibly follow RFC5322 rules.
5	n/a
6	n/a	Eventually HeaderRegistry will be a public API, but it isn't yet,
7	n/a	and will probably change some before that happens.
8	n/a
9	n/a	"""
10	n/a	from types import MappingProxyType
11	n/a
12	n/a	from email import utils
13	n/a	from email import errors
14	n/a	from email import _header_value_parser as parser
15	n/a
16	n/a	class Address:
17	n/a
18	n/a	def __init__(self, display_name='', username='', domain='', addr_spec=None):
19	n/a	"""Create an object representing a full email address.
20	n/a
21	n/a	An address can have a 'display_name', a 'username', and a 'domain'. In
22	n/a	addition to specifying the username and domain separately, they may be
23	n/a	specified together by using the addr_spec keyword instead of the
24	n/a	username and domain keywords. If an addr_spec string is specified it
25	n/a	must be properly quoted according to RFC 5322 rules; an error will be
26	n/a	raised if it is not.
27	n/a
28	n/a	An Address object has display_name, username, domain, and addr_spec
29	n/a	attributes, all of which are read-only. The addr_spec and the string
30	n/a	value of the object are both quoted according to RFC5322 rules, but
31	n/a	without any Content Transfer Encoding.
32	n/a
33	n/a	"""
34	n/a	# This clause with its potential 'raise' may only happen when an
35	n/a	# application program creates an Address object using an addr_spec
36	n/a	# keyword. The email library code itself must always supply username
37	n/a	# and domain.
38	n/a	if addr_spec is not None:
39	n/a	if username or domain:
40	n/a	raise TypeError("addrspec specified when username and/or "
41	n/a	"domain also specified")
42	n/a	a_s, rest = parser.get_addr_spec(addr_spec)
43	n/a	if rest:
44	n/a	raise ValueError("Invalid addr_spec; only '{}' "
45	n/a	"could be parsed from '{}'".format(
46	n/a	a_s, addr_spec))
47	n/a	if a_s.all_defects:
48	n/a	raise a_s.all_defects[0]
49	n/a	username = a_s.local_part
50	n/a	domain = a_s.domain
51	n/a	self._display_name = display_name
52	n/a	self._username = username
53	n/a	self._domain = domain
54	n/a
55	n/a	@property
56	n/a	def display_name(self):
57	n/a	return self._display_name
58	n/a
59	n/a	@property
60	n/a	def username(self):
61	n/a	return self._username
62	n/a
63	n/a	@property
64	n/a	def domain(self):
65	n/a	return self._domain
66	n/a
67	n/a	@property
68	n/a	def addr_spec(self):
69	n/a	"""The addr_spec (username@domain) portion of the address, quoted
70	n/a	according to RFC 5322 rules, but with no Content Transfer Encoding.
71	n/a	"""
72	n/a	nameset = set(self.username)
73	n/a	if len(nameset) > len(nameset-parser.DOT_ATOM_ENDS):
74	n/a	lp = parser.quote_string(self.username)
75	n/a	else:
76	n/a	lp = self.username
77	n/a	if self.domain:
78	n/a	return lp + '@' + self.domain
79	n/a	if not lp:
80	n/a	return '<>'
81	n/a	return lp
82	n/a
83	n/a	def __repr__(self):
84	n/a	return "{}(display_name={!r}, username={!r}, domain={!r})".format(
85	n/a	self.__class__.__name__,
86	n/a	self.display_name, self.username, self.domain)
87	n/a
88	n/a	def __str__(self):
89	n/a	nameset = set(self.display_name)
90	n/a	if len(nameset) > len(nameset-parser.SPECIALS):
91	n/a	disp = parser.quote_string(self.display_name)
92	n/a	else:
93	n/a	disp = self.display_name
94	n/a	if disp:
95	n/a	addr_spec = '' if self.addr_spec=='<>' else self.addr_spec
96	n/a	return "{} <{}>".format(disp, addr_spec)
97	n/a	return self.addr_spec
98	n/a
99	n/a	def __eq__(self, other):
100	n/a	if type(other) != type(self):
101	n/a	return False
102	n/a	return (self.display_name == other.display_name and
103	n/a	self.username == other.username and
104	n/a	self.domain == other.domain)
105	n/a
106	n/a
107	n/a	class Group:
108	n/a
109	n/a	def __init__(self, display_name=None, addresses=None):
110	n/a	"""Create an object representing an address group.
111	n/a
112	n/a	An address group consists of a display_name followed by colon and a
113	n/a	list of addresses (see Address) terminated by a semi-colon. The Group
114	n/a	is created by specifying a display_name and a possibly empty list of
115	n/a	Address objects. A Group can also be used to represent a single
116	n/a	address that is not in a group, which is convenient when manipulating
117	n/a	lists that are a combination of Groups and individual Addresses. In
118	n/a	this case the display_name should be set to None. In particular, the
119	n/a	string representation of a Group whose display_name is None is the same
120	n/a	as the Address object, if there is one and only one Address object in
121	n/a	the addresses list.
122	n/a
123	n/a	"""
124	n/a	self._display_name = display_name
125	n/a	self._addresses = tuple(addresses) if addresses else tuple()
126	n/a
127	n/a	@property
128	n/a	def display_name(self):
129	n/a	return self._display_name
130	n/a
131	n/a	@property
132	n/a	def addresses(self):
133	n/a	return self._addresses
134	n/a
135	n/a	def __repr__(self):
136	n/a	return "{}(display_name={!r}, addresses={!r}".format(
137	n/a	self.__class__.__name__,
138	n/a	self.display_name, self.addresses)
139	n/a
140	n/a	def __str__(self):
141	n/a	if self.display_name is None and len(self.addresses)==1:
142	n/a	return str(self.addresses[0])
143	n/a	disp = self.display_name
144	n/a	if disp is not None:
145	n/a	nameset = set(disp)
146	n/a	if len(nameset) > len(nameset-parser.SPECIALS):
147	n/a	disp = parser.quote_string(disp)
148	n/a	adrstr = ", ".join(str(x) for x in self.addresses)
149	n/a	adrstr = ' ' + adrstr if adrstr else adrstr
150	n/a	return "{}:{};".format(disp, adrstr)
151	n/a
152	n/a	def __eq__(self, other):
153	n/a	if type(other) != type(self):
154	n/a	return False
155	n/a	return (self.display_name == other.display_name and
156	n/a	self.addresses == other.addresses)
157	n/a
158	n/a
159	n/a	# Header Classes #
160	n/a
161	n/a	class BaseHeader(str):
162	n/a
163	n/a	"""Base class for message headers.
164	n/a
165	n/a	Implements generic behavior and provides tools for subclasses.
166	n/a
167	n/a	A subclass must define a classmethod named 'parse' that takes an unfolded
168	n/a	value string and a dictionary as its arguments. The dictionary will
169	n/a	contain one key, 'defects', initialized to an empty list. After the call
170	n/a	the dictionary must contain two additional keys: parse_tree, set to the
171	n/a	parse tree obtained from parsing the header, and 'decoded', set to the
172	n/a	string value of the idealized representation of the data from the value.
173	n/a	(That is, encoded words are decoded, and values that have canonical
174	n/a	representations are so represented.)
175	n/a
176	n/a	The defects key is intended to collect parsing defects, which the message
177	n/a	parser will subsequently dispose of as appropriate. The parser should not,
178	n/a	insofar as practical, raise any errors. Defects should be added to the
179	n/a	list instead. The standard header parsers register defects for RFC
180	n/a	compliance issues, for obsolete RFC syntax, and for unrecoverable parsing
181	n/a	errors.
182	n/a
183	n/a	The parse method may add additional keys to the dictionary. In this case
184	n/a	the subclass must define an 'init' method, which will be passed the
185	n/a	dictionary as its keyword arguments. The method should use (usually by
186	n/a	setting them as the value of similarly named attributes) and remove all the
187	n/a	extra keys added by its parse method, and then use super to call its parent
188	n/a	class with the remaining arguments and keywords.
189	n/a
190	n/a	The subclass should also make sure that a 'max_count' attribute is defined
191	n/a	that is either None or 1. XXX: need to better define this API.
192	n/a
193	n/a	"""
194	n/a
195	n/a	def __new__(cls, name, value):
196	n/a	kwds = {'defects': []}
197	n/a	cls.parse(value, kwds)
198	n/a	if utils._has_surrogates(kwds['decoded']):
199	n/a	kwds['decoded'] = utils._sanitize(kwds['decoded'])
200	n/a	self = str.__new__(cls, kwds['decoded'])
201	n/a	del kwds['decoded']
202	n/a	self.init(name, **kwds)
203	n/a	return self
204	n/a
205	n/a	def init(self, name, *, parse_tree, defects):
206	n/a	self._name = name
207	n/a	self._parse_tree = parse_tree
208	n/a	self._defects = defects
209	n/a
210	n/a	@property
211	n/a	def name(self):
212	n/a	return self._name
213	n/a
214	n/a	@property
215	n/a	def defects(self):
216	n/a	return tuple(self._defects)
217	n/a
218	n/a	def __reduce__(self):
219	n/a	return (
220	n/a	_reconstruct_header,
221	n/a	(
222	n/a	self.__class__.__name__,
223	n/a	self.__class__.__bases__,
224	n/a	str(self),
225	n/a	),
226	n/a	self.__dict__)
227	n/a
228	n/a	@classmethod
229	n/a	def _reconstruct(cls, value):
230	n/a	return str.__new__(cls, value)
231	n/a
232	n/a	def fold(self, *, policy):
233	n/a	"""Fold header according to policy.
234	n/a
235	n/a	The parsed representation of the header is folded according to
236	n/a	RFC5322 rules, as modified by the policy. If the parse tree
237	n/a	contains surrogateescaped bytes, the bytes are CTE encoded using
238	n/a	the charset 'unknown-8bit".
239	n/a
240	n/a	Any non-ASCII characters in the parse tree are CTE encoded using
241	n/a	charset utf-8. XXX: make this a policy setting.
242	n/a
243	n/a	The returned value is an ASCII-only string possibly containing linesep
244	n/a	characters, and ending with a linesep character. The string includes
245	n/a	the header name and the ': ' separator.
246	n/a
247	n/a	"""
248	n/a	# At some point we need to only put fws here if it was in the source.
249	n/a	header = parser.Header([
250	n/a	parser.HeaderLabel([
251	n/a	parser.ValueTerminal(self.name, 'header-name'),
252	n/a	parser.ValueTerminal(':', 'header-sep')]),
253	n/a	parser.CFWSList([parser.WhiteSpaceTerminal(' ', 'fws')]),
254	n/a	self._parse_tree])
255	n/a	return header.fold(policy=policy)
256	n/a
257	n/a
258	n/a	def _reconstruct_header(cls_name, bases, value):
259	n/a	return type(cls_name, bases, {})._reconstruct(value)
260	n/a
261	n/a
262	n/a	class UnstructuredHeader:
263	n/a
264	n/a	max_count = None
265	n/a	value_parser = staticmethod(parser.get_unstructured)
266	n/a
267	n/a	@classmethod
268	n/a	def parse(cls, value, kwds):
269	n/a	kwds['parse_tree'] = cls.value_parser(value)
270	n/a	kwds['decoded'] = str(kwds['parse_tree'])
271	n/a
272	n/a
273	n/a	class UniqueUnstructuredHeader(UnstructuredHeader):
274	n/a
275	n/a	max_count = 1
276	n/a
277	n/a
278	n/a	class DateHeader:
279	n/a
280	n/a	"""Header whose value consists of a single timestamp.
281	n/a
282	n/a	Provides an additional attribute, datetime, which is either an aware
283	n/a	datetime using a timezone, or a naive datetime if the timezone
284	n/a	in the input string is -0000. Also accepts a datetime as input.
285	n/a	The 'value' attribute is the normalized form of the timestamp,
286	n/a	which means it is the output of format_datetime on the datetime.
287	n/a	"""
288	n/a
289	n/a	max_count = None
290	n/a
291	n/a	# This is used only for folding, not for creating 'decoded'.
292	n/a	value_parser = staticmethod(parser.get_unstructured)
293	n/a
294	n/a	@classmethod
295	n/a	def parse(cls, value, kwds):
296	n/a	if not value:
297	n/a	kwds['defects'].append(errors.HeaderMissingRequiredValue())
298	n/a	kwds['datetime'] = None
299	n/a	kwds['decoded'] = ''
300	n/a	kwds['parse_tree'] = parser.TokenList()
301	n/a	return
302	n/a	if isinstance(value, str):
303	n/a	value = utils.parsedate_to_datetime(value)
304	n/a	kwds['datetime'] = value
305	n/a	kwds['decoded'] = utils.format_datetime(kwds['datetime'])
306	n/a	kwds['parse_tree'] = cls.value_parser(kwds['decoded'])
307	n/a
308	n/a	def init(self, args, *kw):
309	n/a	self._datetime = kw.pop('datetime')
310	n/a	super().init(args, *kw)
311	n/a
312	n/a	@property
313	n/a	def datetime(self):
314	n/a	return self._datetime
315	n/a
316	n/a
317	n/a	class UniqueDateHeader(DateHeader):
318	n/a
319	n/a	max_count = 1
320	n/a
321	n/a
322	n/a	class AddressHeader:
323	n/a
324	n/a	max_count = None
325	n/a
326	n/a	@staticmethod
327	n/a	def value_parser(value):
328	n/a	address_list, value = parser.get_address_list(value)
329	n/a	assert not value, 'this should not happen'
330	n/a	return address_list
331	n/a
332	n/a	@classmethod
333	n/a	def parse(cls, value, kwds):
334	n/a	if isinstance(value, str):
335	n/a	# We are translating here from the RFC language (address/mailbox)
336	n/a	# to our API language (group/address).
337	n/a	kwds['parse_tree'] = address_list = cls.value_parser(value)
338	n/a	groups = []
339	n/a	for addr in address_list.addresses:
340	n/a	groups.append(Group(addr.display_name,
341	n/a	[Address(mb.display_name or '',
342	n/a	mb.local_part or '',
343	n/a	mb.domain or '')
344	n/a	for mb in addr.all_mailboxes]))
345	n/a	defects = list(address_list.all_defects)
346	n/a	else:
347	n/a	# Assume it is Address/Group stuff
348	n/a	if not hasattr(value, '__iter__'):
349	n/a	value = [value]
350	n/a	groups = [Group(None, [item]) if not hasattr(item, 'addresses')
351	n/a	else item
352	n/a	for item in value]
353	n/a	defects = []
354	n/a	kwds['groups'] = groups
355	n/a	kwds['defects'] = defects
356	n/a	kwds['decoded'] = ', '.join([str(item) for item in groups])
357	n/a	if 'parse_tree' not in kwds:
358	n/a	kwds['parse_tree'] = cls.value_parser(kwds['decoded'])
359	n/a
360	n/a	def init(self, args, *kw):
361	n/a	self._groups = tuple(kw.pop('groups'))
362	n/a	self._addresses = None
363	n/a	super().init(args, *kw)
364	n/a
365	n/a	@property
366	n/a	def groups(self):
367	n/a	return self._groups
368	n/a
369	n/a	@property
370	n/a	def addresses(self):
371	n/a	if self._addresses is None:
372	n/a	self._addresses = tuple([address for group in self._groups
373	n/a	for address in group.addresses])
374	n/a	return self._addresses
375	n/a
376	n/a
377	n/a	class UniqueAddressHeader(AddressHeader):
378	n/a
379	n/a	max_count = 1
380	n/a
381	n/a
382	n/a	class SingleAddressHeader(AddressHeader):
383	n/a
384	n/a	@property
385	n/a	def address(self):
386	n/a	if len(self.addresses)!=1:
387	n/a	raise ValueError(("value of single address header {} is not "
388	n/a	"a single address").format(self.name))
389	n/a	return self.addresses[0]
390	n/a
391	n/a
392	n/a	class UniqueSingleAddressHeader(SingleAddressHeader):
393	n/a
394	n/a	max_count = 1
395	n/a
396	n/a
397	n/a	class MIMEVersionHeader:
398	n/a
399	n/a	max_count = 1
400	n/a
401	n/a	value_parser = staticmethod(parser.parse_mime_version)
402	n/a
403	n/a	@classmethod
404	n/a	def parse(cls, value, kwds):
405	n/a	kwds['parse_tree'] = parse_tree = cls.value_parser(value)
406	n/a	kwds['decoded'] = str(parse_tree)
407	n/a	kwds['defects'].extend(parse_tree.all_defects)
408	n/a	kwds['major'] = None if parse_tree.minor is None else parse_tree.major
409	n/a	kwds['minor'] = parse_tree.minor
410	n/a	if parse_tree.minor is not None:
411	n/a	kwds['version'] = '{}.{}'.format(kwds['major'], kwds['minor'])
412	n/a	else:
413	n/a	kwds['version'] = None
414	n/a
415	n/a	def init(self, args, *kw):
416	n/a	self._version = kw.pop('version')
417	n/a	self._major = kw.pop('major')
418	n/a	self._minor = kw.pop('minor')
419	n/a	super().init(args, *kw)
420	n/a
421	n/a	@property
422	n/a	def major(self):
423	n/a	return self._major
424	n/a
425	n/a	@property
426	n/a	def minor(self):
427	n/a	return self._minor
428	n/a
429	n/a	@property
430	n/a	def version(self):
431	n/a	return self._version
432	n/a
433	n/a
434	n/a	class ParameterizedMIMEHeader:
435	n/a
436	n/a	# Mixin that handles the params dict. Must be subclassed and
437	n/a	# a property value_parser for the specific header provided.
438	n/a
439	n/a	max_count = 1
440	n/a
441	n/a	@classmethod
442	n/a	def parse(cls, value, kwds):
443	n/a	kwds['parse_tree'] = parse_tree = cls.value_parser(value)
444	n/a	kwds['decoded'] = str(parse_tree)
445	n/a	kwds['defects'].extend(parse_tree.all_defects)
446	n/a	if parse_tree.params is None:
447	n/a	kwds['params'] = {}
448	n/a	else:
449	n/a	# The MIME RFCs specify that parameter ordering is arbitrary.
450	n/a	kwds['params'] = {utils._sanitize(name).lower():
451	n/a	utils._sanitize(value)
452	n/a	for name, value in parse_tree.params}
453	n/a
454	n/a	def init(self, args, *kw):
455	n/a	self._params = kw.pop('params')
456	n/a	super().init(args, *kw)
457	n/a
458	n/a	@property
459	n/a	def params(self):
460	n/a	return MappingProxyType(self._params)
461	n/a
462	n/a
463	n/a	class ContentTypeHeader(ParameterizedMIMEHeader):
464	n/a
465	n/a	value_parser = staticmethod(parser.parse_content_type_header)
466	n/a
467	n/a	def init(self, args, *kw):
468	n/a	super().init(args, *kw)
469	n/a	self._maintype = utils._sanitize(self._parse_tree.maintype)
470	n/a	self._subtype = utils._sanitize(self._parse_tree.subtype)
471	n/a
472	n/a	@property
473	n/a	def maintype(self):
474	n/a	return self._maintype
475	n/a
476	n/a	@property
477	n/a	def subtype(self):
478	n/a	return self._subtype
479	n/a
480	n/a	@property
481	n/a	def content_type(self):
482	n/a	return self.maintype + '/' + self.subtype
483	n/a
484	n/a
485	n/a	class ContentDispositionHeader(ParameterizedMIMEHeader):
486	n/a
487	n/a	value_parser = staticmethod(parser.parse_content_disposition_header)
488	n/a
489	n/a	def init(self, args, *kw):
490	n/a	super().init(args, *kw)
491	n/a	cd = self._parse_tree.content_disposition
492	n/a	self._content_disposition = cd if cd is None else utils._sanitize(cd)
493	n/a
494	n/a	@property
495	n/a	def content_disposition(self):
496	n/a	return self._content_disposition
497	n/a
498	n/a
499	n/a	class ContentTransferEncodingHeader:
500	n/a
501	n/a	max_count = 1
502	n/a
503	n/a	value_parser = staticmethod(parser.parse_content_transfer_encoding_header)
504	n/a
505	n/a	@classmethod
506	n/a	def parse(cls, value, kwds):
507	n/a	kwds['parse_tree'] = parse_tree = cls.value_parser(value)
508	n/a	kwds['decoded'] = str(parse_tree)
509	n/a	kwds['defects'].extend(parse_tree.all_defects)
510	n/a
511	n/a	def init(self, args, *kw):
512	n/a	super().init(args, *kw)
513	n/a	self._cte = utils._sanitize(self._parse_tree.cte)
514	n/a
515	n/a	@property
516	n/a	def cte(self):
517	n/a	return self._cte
518	n/a
519	n/a
520	n/a	# The header factory #
521	n/a
522	n/a	_default_header_map = {
523	n/a	'subject': UniqueUnstructuredHeader,
524	n/a	'date': UniqueDateHeader,
525	n/a	'resent-date': DateHeader,
526	n/a	'orig-date': UniqueDateHeader,
527	n/a	'sender': UniqueSingleAddressHeader,
528	n/a	'resent-sender': SingleAddressHeader,
529	n/a	'to': UniqueAddressHeader,
530	n/a	'resent-to': AddressHeader,
531	n/a	'cc': UniqueAddressHeader,
532	n/a	'resent-cc': AddressHeader,
533	n/a	'bcc': UniqueAddressHeader,
534	n/a	'resent-bcc': AddressHeader,
535	n/a	'from': UniqueAddressHeader,
536	n/a	'resent-from': AddressHeader,
537	n/a	'reply-to': UniqueAddressHeader,
538	n/a	'mime-version': MIMEVersionHeader,
539	n/a	'content-type': ContentTypeHeader,
540	n/a	'content-disposition': ContentDispositionHeader,
541	n/a	'content-transfer-encoding': ContentTransferEncodingHeader,
542	n/a	}
543	n/a
544	n/a	class HeaderRegistry:
545	n/a
546	n/a	"""A header_factory and header registry."""
547	n/a
548	n/a	def __init__(self, base_class=BaseHeader, default_class=UnstructuredHeader,
549	n/a	use_default_map=True):
550	n/a	"""Create a header_factory that works with the Policy API.
551	n/a
552	n/a	base_class is the class that will be the last class in the created
553	n/a	header class's __bases__ list. default_class is the class that will be
554	n/a	used if "name" (see __call__) does not appear in the registry.
555	n/a	use_default_map controls whether or not the default mapping of names to
556	n/a	specialized classes is copied in to the registry when the factory is
557	n/a	created. The default is True.
558	n/a
559	n/a	"""
560	n/a	self.registry = {}
561	n/a	self.base_class = base_class
562	n/a	self.default_class = default_class
563	n/a	if use_default_map:
564	n/a	self.registry.update(_default_header_map)
565	n/a
566	n/a	def map_to_type(self, name, cls):
567	n/a	"""Register cls as the specialized class for handling "name" headers.
568	n/a
569	n/a	"""
570	n/a	self.registry[name.lower()] = cls
571	n/a
572	n/a	def __getitem__(self, name):
573	n/a	cls = self.registry.get(name.lower(), self.default_class)
574	n/a	return type('_'+cls.__name__, (cls, self.base_class), {})
575	n/a
576	n/a	def __call__(self, name, value):
577	n/a	"""Create a header instance for header 'name' from 'value'.
578	n/a
579	n/a	Creates a header instance by creating a specialized class for parsing
580	n/a	and representing the specified header by combining the factory
581	n/a	base_class with a specialized class from the registry or the
582	n/a	default_class, and passing the name and value to the constructed
583	n/a	class's constructor.
584	n/a
585	n/a	"""
586	n/a	return self[name](name, value)