1 # Copyright (C) 2001-2006 Python Software Foundation
2 # Author: Ben Gertzfield
3 # Contact: email-sig@python.org
5 """Quoted-printable content transfer encoding per RFCs 2045-2047.
7 This module handles the content transfer encoding method defined in RFC 2045
8 to encode US ASCII-like 8-bit data called `quoted-printable'. It is used to
9 safely encode text that is in a character set similar to the 7-bit US ASCII
10 character set, but that includes some 8-bit characters that are normally not
11 allowed in email bodies or headers.
13 Quoted-printable is very space-inefficient for encoding binary files; use the
14 email.base64MIME module for that instead.
16 This module provides an interface to encode and decode both headers and bodies
17 with quoted-printable encoding.
19 RFC 2045 defines a method for including character set information in an
20 `encoded-word' in a header. This method is commonly used for 8-bit real names
21 in To:/From:/Cc: etc. fields, as well as Subject: lines.
23 This module does not do the line wrapping or end-of-line character
24 conversion necessary for proper internationalized headers; it only
25 does dumb encoding and decoding. To deal with the various line
26 wrapping issues, use the email.Header module.
40 'header_quopri_check',
48 from string
import hexdigits
49 from email
.utils
import fix_eols
57 hqre
= re
.compile(r
'[^-a-zA-Z0-9!*+/ ]')
58 bqre
= re
.compile(r
'[^ !-<>-~\t]')
63 def header_quopri_check(c
):
64 """Return True if the character should be escaped with header quopri."""
65 return bool(hqre
.match(c
))
68 def body_quopri_check(c
):
69 """Return True if the character should be escaped with body quopri."""
70 return bool(bqre
.match(c
))
73 def header_quopri_len(s
):
74 """Return the length of str when it is encoded with header quopri."""
84 def body_quopri_len(str):
85 """Return the length of str when it is encoded with body quopri."""
95 def _max_append(L
, s
, maxlen
, extra
=''):
98 elif len(L
[-1]) + len(s
) <= maxlen
:
105 """Turn a string in the form =AB to the ASCII character with value 0xab"""
106 return chr(int(s
[1:3], 16))
110 return "=%02X" % ord(c
)
114 def header_encode(header
, charset
="iso-8859-1", keep_eols
=False,
115 maxlinelen
=76, eol
=NL
):
116 """Encode a single header line with quoted-printable (like) encoding.
118 Defined in RFC 2045, this `Q' encoding is similar to quoted-printable, but
119 used specifically for email header fields to allow charsets with mostly 7
120 bit characters (and some 8 bit) to remain more or less readable in non-RFC
121 2045 aware mail clients.
123 charset names the character set to use to encode the header. It defaults
126 The resulting string will be in the form:
128 "=?charset?q?I_f=E2rt_in_your_g=E8n=E8ral_dire=E7tion?\\n
129 =?charset?q?Silly_=C8nglish_Kn=EEghts?="
131 with each line wrapped safely at, at most, maxlinelen characters (defaults
132 to 76 characters). If maxlinelen is None, the entire string is encoded in
133 one chunk with no splitting.
135 End-of-line characters (\\r, \\n, \\r\\n) will be automatically converted
136 to the canonical email line separator \\r\\n unless the keep_eols
137 parameter is True (the default is False).
139 Each line of the header will be terminated in the value of eol, which
140 defaults to "\\n". Set this to "\\r\\n" if you are using the result of
141 this function directly in email.
143 # Return empty headers unchanged
148 header
= fix_eols(header
)
150 # Quopri encode each line, in encoded chunks no greater than maxlinelen in
151 # length, after the RFC chrome is added in.
153 if maxlinelen
is None:
154 # An obnoxiously large number that's good enough
157 max_encoded
= maxlinelen
- len(charset
) - MISC_LEN
- 1
160 # Space may be represented as _ instead of =20 for readability
162 _max_append(quoted
, '_', max_encoded
)
163 # These characters can be included verbatim
164 elif not hqre
.match(c
):
165 _max_append(quoted
, c
, max_encoded
)
166 # Otherwise, replace with hex value like =E2
168 _max_append(quoted
, "=%02X" % ord(c
), max_encoded
)
170 # Now add the RFC chrome to each encoded chunk and glue the chunks
171 # together. BAW: should we be able to specify the leading whitespace in
174 return joiner
.join(['=?%s?q?%s?=' % (charset
, line
) for line
in quoted
])
178 def encode(body
, binary
=False, maxlinelen
=76, eol
=NL
):
179 """Encode with quoted-printable, wrapping at maxlinelen characters.
181 If binary is False (the default), end-of-line characters will be converted
182 to the canonical email end-of-line sequence \\r\\n. Otherwise they will
185 Each line of encoded text will end with eol, which defaults to "\\n". Set
186 this to "\\r\\n" if you will be using the result of this function directly
189 Each line will be wrapped at, at most, maxlinelen characters (defaults to
190 76 characters). Long lines will have the `soft linefeed' quoted-printable
191 character "=" appended to them, so the decoded text will be identical to
198 body
= fix_eols(body
)
200 # BAW: We're accumulating the body text by string concatenation. That
201 # can't be very efficient, but I don't have time now to rewrite it. It
202 # just feels like this algorithm could be more efficient.
205 # Preserve line endings here so we can check later to see an eol needs to
206 # be added to the output later.
207 lines
= body
.splitlines(1)
209 # But strip off line-endings for processing this line.
210 if line
.endswith(CRLF
):
212 elif line
[-1] in CRLF
:
219 # Now we need to examine every character to see if it needs to be
220 # quopri encoded. BAW: again, string concatenation is inefficient.
221 for j
in range(linelen
):
227 # Check for whitespace at end of line; special case
232 # Check to see to see if the line has reached its maximum length
233 if len(encoded_line
) + len(c
) >= maxlinelen
:
234 encoded_body
+= encoded_line
+ '=' + eol
237 # Now at end of line..
238 if prev
and prev
in ' \t':
239 # Special case for whitespace at end of file
240 if lineno
+ 1 == len(lines
):
242 if len(encoded_line
) + len(prev
) > maxlinelen
:
243 encoded_body
+= encoded_line
+ '=' + eol
+ prev
245 encoded_body
+= encoded_line
+ prev
246 # Just normal whitespace at end of line
248 encoded_body
+= encoded_line
+ prev
+ '=' + eol
250 # Now look at the line we just finished and it has a line ending, we
251 # need to add eol to the end of the line.
252 if lines
[lineno
].endswith(CRLF
) or lines
[lineno
][-1] in CRLF
:
253 encoded_body
+= encoded_line
+ eol
255 encoded_body
+= encoded_line
260 # For convenience and backwards compatibility w/ standard base64 module
262 encodestring
= encode
266 # BAW: I'm not sure if the intent was for the signature of this function to be
267 # the same as base64MIME.decode() or not...
268 def decode(encoded
, eol
=NL
):
269 """Decode a quoted-printable string.
271 Lines are separated with eol, which defaults to \\n.
275 # BAW: see comment in encode() above. Again, we're building up the
276 # decoded string with string concatenation, which could be done much more
280 for line
in encoded
.splitlines():
293 # Otherwise, c == "=". Are we at the end of the line? If so, add
298 # Decode if in form =AB
299 elif i
+2 < n
and line
[i
+1] in hexdigits
and line
[i
+2] in hexdigits
:
300 decoded
+= unquote(line
[i
:i
+3])
302 # Otherwise, not in form =AB, pass literally
309 # Special case if original string did not end with eol
310 if not encoded
.endswith(eol
) and decoded
.endswith(eol
):
311 decoded
= decoded
[:-1]
315 # For convenience and backwards compatibility w/ standard base64 module
317 decodestring
= decode
321 def _unquote_match(match
):
322 """Turn a match in the form =AB to the ASCII character with value 0xab"""
327 # Header decoding is done a bit differently
328 def header_decode(s
):
329 """Decode a string encoded with RFC 2045 MIME header `Q' encoding.
331 This function does not parse a full MIME header value encoded with
332 quoted-printable (like =?iso-8895-1?q?Hello_World?=) -- please use
333 the high level email.Header class for that functionality.
335 s
= s
.replace('_', ' ')
336 return re
.sub(r
'=\w{2}', _unquote_match
, s
)