Python code coverage for Lib/email/quoprimime.py

#	count	content
1	n/a	# Copyright (C) 2001-2006 Python Software Foundation
2	n/a	# Author: Ben Gertzfield
3	n/a	# Contact: email-sig@python.org
4	n/a
5	n/a	"""Quoted-printable content transfer encoding per RFCs 2045-2047.
6	n/a
7	n/a	This module handles the content transfer encoding method defined in RFC 2045
8	n/a	to encode US ASCII-like 8-bit data called `quoted-printable'. It is used to
9	n/a	safely encode text that is in a character set similar to the 7-bit US ASCII
10	n/a	character set, but that includes some 8-bit characters that are normally not
11	n/a	allowed in email bodies or headers.
12	n/a
13	n/a	Quoted-printable is very space-inefficient for encoding binary files; use the
14	n/a	email.base64mime module for that instead.
15	n/a
16	n/a	This module provides an interface to encode and decode both headers and bodies
17	n/a	with quoted-printable encoding.
18	n/a
19	n/a	RFC 2045 defines a method for including character set information in an
20	n/a	`encoded-word' in a header. This method is commonly used for 8-bit real names
21	n/a	in To:/From:/Cc: etc. fields, as well as Subject: lines.
22	n/a
23	n/a	This module does not do the line wrapping or end-of-line character
24	n/a	conversion necessary for proper internationalized headers; it only
25	n/a	does dumb encoding and decoding. To deal with the various line
26	n/a	wrapping issues, use the email.header module.
27	n/a	"""
28	n/a
29	n/a	__all__ = [
30	n/a	'body_decode',
31	n/a	'body_encode',
32	n/a	'body_length',
33	n/a	'decode',
34	n/a	'decodestring',
35	n/a	'header_decode',
36	n/a	'header_encode',
37	n/a	'header_length',
38	n/a	'quote',
39	n/a	'unquote',
40	n/a	]
41	n/a
42	n/a	import re
43	n/a
44	n/a	from string import ascii_letters, digits, hexdigits
45	n/a
46	n/a	CRLF = '\r\n'
47	n/a	NL = '\n'
48	n/a	EMPTYSTRING = ''
49	n/a
50	n/a	# Build a mapping of octets to the expansion of that octet. Since we're only
51	n/a	# going to have 256 of these things, this isn't terribly inefficient
52	n/a	# space-wise. Remember that headers and bodies have different sets of safe
53	n/a	# characters. Initialize both maps with the full expansion, and then override
54	n/a	# the safe bytes with the more compact form.
55	n/a	_QUOPRI_MAP = ['=%02X' % c for c in range(256)]
56	n/a	_QUOPRI_HEADER_MAP = _QUOPRI_MAP[:]
57	n/a	_QUOPRI_BODY_MAP = _QUOPRI_MAP[:]
58	n/a
59	n/a	# Safe header bytes which need no encoding.
60	n/a	for c in b'-!*+/' + ascii_letters.encode('ascii') + digits.encode('ascii'):
61	n/a	_QUOPRI_HEADER_MAP[c] = chr(c)
62	n/a	# Headers have one other special encoding; spaces become underscores.
63	n/a	_QUOPRI_HEADER_MAP[ord(' ')] = '_'
64	n/a
65	n/a	# Safe body bytes which need no encoding.
66	n/a	for c in (b' !"#$%&\'()*+,-./0123456789:;<>'
67	n/a	b'?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`'
68	n/a	b'abcdefghijklmnopqrstuvwxyz{\|}~\t'):
69	n/a	_QUOPRI_BODY_MAP[c] = chr(c)
70	n/a
71	n/a
72	n/a
73	n/a	# Helpers
74	n/a	def header_check(octet):
75	n/a	"""Return True if the octet should be escaped with header quopri."""
76	n/a	return chr(octet) != _QUOPRI_HEADER_MAP[octet]
77	n/a
78	n/a
79	n/a	def body_check(octet):
80	n/a	"""Return True if the octet should be escaped with body quopri."""
81	n/a	return chr(octet) != _QUOPRI_BODY_MAP[octet]
82	n/a
83	n/a
84	n/a	def header_length(bytearray):
85	n/a	"""Return a header quoted-printable encoding length.
86	n/a
87	n/a	Note that this does not include any RFC 2047 chrome added by
88	n/a	`header_encode()`.
89	n/a
90	n/a	:param bytearray: An array of bytes (a.k.a. octets).
91	n/a	:return: The length in bytes of the byte array when it is encoded with
92	n/a	quoted-printable for headers.
93	n/a	"""
94	n/a	return sum(len(_QUOPRI_HEADER_MAP[octet]) for octet in bytearray)
95	n/a
96	n/a
97	n/a	def body_length(bytearray):
98	n/a	"""Return a body quoted-printable encoding length.
99	n/a
100	n/a	:param bytearray: An array of bytes (a.k.a. octets).
101	n/a	:return: The length in bytes of the byte array when it is encoded with
102	n/a	quoted-printable for bodies.
103	n/a	"""
104	n/a	return sum(len(_QUOPRI_BODY_MAP[octet]) for octet in bytearray)
105	n/a
106	n/a
107	n/a	def _max_append(L, s, maxlen, extra=''):
108	n/a	if not isinstance(s, str):
109	n/a	s = chr(s)
110	n/a	if not L:
111	n/a	L.append(s.lstrip())
112	n/a	elif len(L[-1]) + len(s) <= maxlen:
113	n/a	L[-1] += extra + s
114	n/a	else:
115	n/a	L.append(s.lstrip())
116	n/a
117	n/a
118	n/a	def unquote(s):
119	n/a	"""Turn a string in the form =AB to the ASCII character with value 0xab"""
120	n/a	return chr(int(s[1:3], 16))
121	n/a
122	n/a
123	n/a	def quote(c):
124	n/a	return _QUOPRI_MAP[ord(c)]
125	n/a
126	n/a
127	n/a	def header_encode(header_bytes, charset='iso-8859-1'):
128	n/a	"""Encode a single header line with quoted-printable (like) encoding.
129	n/a
130	n/a	Defined in RFC 2045, this `Q' encoding is similar to quoted-printable, but
131	n/a	used specifically for email header fields to allow charsets with mostly 7
132	n/a	bit characters (and some 8 bit) to remain more or less readable in non-RFC
133	n/a	2045 aware mail clients.
134	n/a
135	n/a	charset names the character set to use in the RFC 2046 header. It
136	n/a	defaults to iso-8859-1.
137	n/a	"""
138	n/a	# Return empty headers as an empty string.
139	n/a	if not header_bytes:
140	n/a	return ''
141	n/a	# Iterate over every byte, encoding if necessary.
142	n/a	encoded = header_bytes.decode('latin1').translate(_QUOPRI_HEADER_MAP)
143	n/a	# Now add the RFC chrome to each encoded chunk and glue the chunks
144	n/a	# together.
145	n/a	return '=?%s?q?%s?=' % (charset, encoded)
146	n/a
147	n/a
148	n/a	_QUOPRI_BODY_ENCODE_MAP = _QUOPRI_BODY_MAP[:]
149	n/a	for c in b'\r\n':
150	n/a	_QUOPRI_BODY_ENCODE_MAP[c] = chr(c)
151	n/a
152	n/a	def body_encode(body, maxlinelen=76, eol=NL):
153	n/a	"""Encode with quoted-printable, wrapping at maxlinelen characters.
154	n/a
155	n/a	Each line of encoded text will end with eol, which defaults to "\\n". Set
156	n/a	this to "\\r\\n" if you will be using the result of this function directly
157	n/a	in an email.
158	n/a
159	n/a	Each line will be wrapped at, at most, maxlinelen characters before the
160	n/a	eol string (maxlinelen defaults to 76 characters, the maximum value
161	n/a	permitted by RFC 2045). Long lines will have the 'soft line break'
162	n/a	quoted-printable character "=" appended to them, so the decoded text will
163	n/a	be identical to the original text.
164	n/a
165	n/a	The minimum maxlinelen is 4 to have room for a quoted character ("=XX")
166	n/a	followed by a soft line break. Smaller values will generate a
167	n/a	ValueError.
168	n/a
169	n/a	"""
170	n/a
171	n/a	if maxlinelen < 4:
172	n/a	raise ValueError("maxlinelen must be at least 4")
173	n/a	if not body:
174	n/a	return body
175	n/a
176	n/a	# quote speacial characters
177	n/a	body = body.translate(_QUOPRI_BODY_ENCODE_MAP)
178	n/a
179	n/a	soft_break = '=' + eol
180	n/a	# leave space for the '=' at the end of a line
181	n/a	maxlinelen1 = maxlinelen - 1
182	n/a
183	n/a	encoded_body = []
184	n/a	append = encoded_body.append
185	n/a
186	n/a	for line in body.splitlines():
187	n/a	# break up the line into pieces no longer than maxlinelen - 1
188	n/a	start = 0
189	n/a	laststart = len(line) - 1 - maxlinelen
190	n/a	while start <= laststart:
191	n/a	stop = start + maxlinelen1
192	n/a	# make sure we don't break up an escape sequence
193	n/a	if line[stop - 2] == '=':
194	n/a	append(line[start:stop - 1])
195	n/a	start = stop - 2
196	n/a	elif line[stop - 1] == '=':
197	n/a	append(line[start:stop])
198	n/a	start = stop - 1
199	n/a	else:
200	n/a	append(line[start:stop] + '=')
201	n/a	start = stop
202	n/a
203	n/a	# handle rest of line, special case if line ends in whitespace
204	n/a	if line and line[-1] in ' \t':
205	n/a	room = start - laststart
206	n/a	if room >= 3:
207	n/a	# It's a whitespace character at end-of-line, and we have room
208	n/a	# for the three-character quoted encoding.
209	n/a	q = quote(line[-1])
210	n/a	elif room == 2:
211	n/a	# There's room for the whitespace character and a soft break.
212	n/a	q = line[-1] + soft_break
213	n/a	else:
214	n/a	# There's room only for a soft break. The quoted whitespace
215	n/a	# will be the only content on the subsequent line.
216	n/a	q = soft_break + quote(line[-1])
217	n/a	append(line[start:-1] + q)
218	n/a	else:
219	n/a	append(line[start:])
220	n/a
221	n/a	# add back final newline if present
222	n/a	if body[-1] in CRLF:
223	n/a	append('')
224	n/a
225	n/a	return eol.join(encoded_body)
226	n/a
227	n/a
228	n/a
229	n/a	# BAW: I'm not sure if the intent was for the signature of this function to be
230	n/a	# the same as base64MIME.decode() or not...
231	n/a	def decode(encoded, eol=NL):
232	n/a	"""Decode a quoted-printable string.
233	n/a
234	n/a	Lines are separated with eol, which defaults to \\n.
235	n/a	"""
236	n/a	if not encoded:
237	n/a	return encoded
238	n/a	# BAW: see comment in encode() above. Again, we're building up the
239	n/a	# decoded string with string concatenation, which could be done much more
240	n/a	# efficiently.
241	n/a	decoded = ''
242	n/a
243	n/a	for line in encoded.splitlines():
244	n/a	line = line.rstrip()
245	n/a	if not line:
246	n/a	decoded += eol
247	n/a	continue
248	n/a
249	n/a	i = 0
250	n/a	n = len(line)
251	n/a	while i < n:
252	n/a	c = line[i]
253	n/a	if c != '=':
254	n/a	decoded += c
255	n/a	i += 1
256	n/a	# Otherwise, c == "=". Are we at the end of the line? If so, add
257	n/a	# a soft line break.
258	n/a	elif i+1 == n:
259	n/a	i += 1
260	n/a	continue
261	n/a	# Decode if in form =AB
262	n/a	elif i+2 < n and line[i+1] in hexdigits and line[i+2] in hexdigits:
263	n/a	decoded += unquote(line[i:i+3])
264	n/a	i += 3
265	n/a	# Otherwise, not in form =AB, pass literally
266	n/a	else:
267	n/a	decoded += c
268	n/a	i += 1
269	n/a
270	n/a	if i == n:
271	n/a	decoded += eol
272	n/a	# Special case if original string did not end with eol
273	n/a	if encoded[-1] not in '\r\n' and decoded.endswith(eol):
274	n/a	decoded = decoded[:-1]
275	n/a	return decoded
276	n/a
277	n/a
278	n/a	# For convenience and backwards compatibility w/ standard base64 module
279	n/a	body_decode = decode
280	n/a	decodestring = decode
281	n/a
282	n/a
283	n/a
284	n/a	def _unquote_match(match):
285	n/a	"""Turn a match in the form =AB to the ASCII character with value 0xab"""
286	n/a	s = match.group(0)
287	n/a	return unquote(s)
288	n/a
289	n/a
290	n/a	# Header decoding is done a bit differently
291	n/a	def header_decode(s):
292	n/a	"""Decode a string encoded with RFC 2045 MIME header `Q' encoding.
293	n/a
294	n/a	This function does not parse a full MIME header value encoded with
295	n/a	quoted-printable (like =?iso-8859-1?q?Hello_World?=) -- please use
296	n/a	the high level email.header class for that functionality.
297	n/a	"""
298	n/a	s = s.replace('_', ' ')
299	n/a	return re.sub(r'=[a-fA-F0-9]{2}', _unquote_match, s, flags=re.ASCII)