ยปCore Development>Code coverage>Lib/email/quoprimime.py

Python code coverage for Lib/email/quoprimime.py

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