|
jpayne@69
|
1 # Copyright (C) 2002-2007 Python Software Foundation
|
|
jpayne@69
|
2 # Author: Ben Gertzfield
|
|
jpayne@69
|
3 # Contact: email-sig@python.org
|
|
jpayne@69
|
4
|
|
jpayne@69
|
5 """Base64 content transfer encoding per RFCs 2045-2047.
|
|
jpayne@69
|
6
|
|
jpayne@69
|
7 This module handles the content transfer encoding method defined in RFC 2045
|
|
jpayne@69
|
8 to encode arbitrary 8-bit data using the three 8-bit bytes in four 7-bit
|
|
jpayne@69
|
9 characters encoding known as Base64.
|
|
jpayne@69
|
10
|
|
jpayne@69
|
11 It is used in the MIME standards for email to attach images, audio, and text
|
|
jpayne@69
|
12 using some 8-bit character sets to messages.
|
|
jpayne@69
|
13
|
|
jpayne@69
|
14 This module provides an interface to encode and decode both headers and bodies
|
|
jpayne@69
|
15 with Base64 encoding.
|
|
jpayne@69
|
16
|
|
jpayne@69
|
17 RFC 2045 defines a method for including character set information in an
|
|
jpayne@69
|
18 `encoded-word' in a header. This method is commonly used for 8-bit real names
|
|
jpayne@69
|
19 in To:, From:, Cc:, etc. fields, as well as Subject: lines.
|
|
jpayne@69
|
20
|
|
jpayne@69
|
21 This module does not do the line wrapping or end-of-line character conversion
|
|
jpayne@69
|
22 necessary for proper internationalized headers; it only does dumb encoding and
|
|
jpayne@69
|
23 decoding. To deal with the various line wrapping issues, use the email.header
|
|
jpayne@69
|
24 module.
|
|
jpayne@69
|
25 """
|
|
jpayne@69
|
26
|
|
jpayne@69
|
27 __all__ = [
|
|
jpayne@69
|
28 'body_decode',
|
|
jpayne@69
|
29 'body_encode',
|
|
jpayne@69
|
30 'decode',
|
|
jpayne@69
|
31 'decodestring',
|
|
jpayne@69
|
32 'header_encode',
|
|
jpayne@69
|
33 'header_length',
|
|
jpayne@69
|
34 ]
|
|
jpayne@69
|
35
|
|
jpayne@69
|
36
|
|
jpayne@69
|
37 from base64 import b64encode
|
|
jpayne@69
|
38 from binascii import b2a_base64, a2b_base64
|
|
jpayne@69
|
39
|
|
jpayne@69
|
40 CRLF = '\r\n'
|
|
jpayne@69
|
41 NL = '\n'
|
|
jpayne@69
|
42 EMPTYSTRING = ''
|
|
jpayne@69
|
43
|
|
jpayne@69
|
44 # See also Charset.py
|
|
jpayne@69
|
45 MISC_LEN = 7
|
|
jpayne@69
|
46
|
|
jpayne@69
|
47
|
|
jpayne@69
|
48
|
|
jpayne@69
|
49 # Helpers
|
|
jpayne@69
|
50 def header_length(bytearray):
|
|
jpayne@69
|
51 """Return the length of s when it is encoded with base64."""
|
|
jpayne@69
|
52 groups_of_3, leftover = divmod(len(bytearray), 3)
|
|
jpayne@69
|
53 # 4 bytes out for each 3 bytes (or nonzero fraction thereof) in.
|
|
jpayne@69
|
54 n = groups_of_3 * 4
|
|
jpayne@69
|
55 if leftover:
|
|
jpayne@69
|
56 n += 4
|
|
jpayne@69
|
57 return n
|
|
jpayne@69
|
58
|
|
jpayne@69
|
59
|
|
jpayne@69
|
60
|
|
jpayne@69
|
61 def header_encode(header_bytes, charset='iso-8859-1'):
|
|
jpayne@69
|
62 """Encode a single header line with Base64 encoding in a given charset.
|
|
jpayne@69
|
63
|
|
jpayne@69
|
64 charset names the character set to use to encode the header. It defaults
|
|
jpayne@69
|
65 to iso-8859-1. Base64 encoding is defined in RFC 2045.
|
|
jpayne@69
|
66 """
|
|
jpayne@69
|
67 if not header_bytes:
|
|
jpayne@69
|
68 return ""
|
|
jpayne@69
|
69 if isinstance(header_bytes, str):
|
|
jpayne@69
|
70 header_bytes = header_bytes.encode(charset)
|
|
jpayne@69
|
71 encoded = b64encode(header_bytes).decode("ascii")
|
|
jpayne@69
|
72 return '=?%s?b?%s?=' % (charset, encoded)
|
|
jpayne@69
|
73
|
|
jpayne@69
|
74
|
|
jpayne@69
|
75
|
|
jpayne@69
|
76 def body_encode(s, maxlinelen=76, eol=NL):
|
|
jpayne@69
|
77 r"""Encode a string with base64.
|
|
jpayne@69
|
78
|
|
jpayne@69
|
79 Each line will be wrapped at, at most, maxlinelen characters (defaults to
|
|
jpayne@69
|
80 76 characters).
|
|
jpayne@69
|
81
|
|
jpayne@69
|
82 Each line of encoded text will end with eol, which defaults to "\n". Set
|
|
jpayne@69
|
83 this to "\r\n" if you will be using the result of this function directly
|
|
jpayne@69
|
84 in an email.
|
|
jpayne@69
|
85 """
|
|
jpayne@69
|
86 if not s:
|
|
jpayne@69
|
87 return s
|
|
jpayne@69
|
88
|
|
jpayne@69
|
89 encvec = []
|
|
jpayne@69
|
90 max_unencoded = maxlinelen * 3 // 4
|
|
jpayne@69
|
91 for i in range(0, len(s), max_unencoded):
|
|
jpayne@69
|
92 # BAW: should encode() inherit b2a_base64()'s dubious behavior in
|
|
jpayne@69
|
93 # adding a newline to the encoded string?
|
|
jpayne@69
|
94 enc = b2a_base64(s[i:i + max_unencoded]).decode("ascii")
|
|
jpayne@69
|
95 if enc.endswith(NL) and eol != NL:
|
|
jpayne@69
|
96 enc = enc[:-1] + eol
|
|
jpayne@69
|
97 encvec.append(enc)
|
|
jpayne@69
|
98 return EMPTYSTRING.join(encvec)
|
|
jpayne@69
|
99
|
|
jpayne@69
|
100
|
|
jpayne@69
|
101
|
|
jpayne@69
|
102 def decode(string):
|
|
jpayne@69
|
103 """Decode a raw base64 string, returning a bytes object.
|
|
jpayne@69
|
104
|
|
jpayne@69
|
105 This function does not parse a full MIME header value encoded with
|
|
jpayne@69
|
106 base64 (like =?iso-8859-1?b?bmloISBuaWgh?=) -- please use the high
|
|
jpayne@69
|
107 level email.header class for that functionality.
|
|
jpayne@69
|
108 """
|
|
jpayne@69
|
109 if not string:
|
|
jpayne@69
|
110 return bytes()
|
|
jpayne@69
|
111 elif isinstance(string, str):
|
|
jpayne@69
|
112 return a2b_base64(string.encode('raw-unicode-escape'))
|
|
jpayne@69
|
113 else:
|
|
jpayne@69
|
114 return a2b_base64(string)
|
|
jpayne@69
|
115
|
|
jpayne@69
|
116
|
|
jpayne@69
|
117 # For convenience and backwards compatibility w/ standard base64 module
|
|
jpayne@69
|
118 body_decode = decode
|
|
jpayne@69
|
119 decodestring = decode
|
