]>
Commit | Line | Data |
---|---|---|
4710c53d | 1 | # Copyright (C) 2002-2006 Python Software Foundation\r |
2 | # Author: Ben Gertzfield\r | |
3 | # Contact: email-sig@python.org\r | |
4 | \r | |
5 | """Base64 content transfer encoding per RFCs 2045-2047.\r | |
6 | \r | |
7 | This module handles the content transfer encoding method defined in RFC 2045\r | |
8 | to encode arbitrary 8-bit data using the three 8-bit bytes in four 7-bit\r | |
9 | characters encoding known as Base64.\r | |
10 | \r | |
11 | It is used in the MIME standards for email to attach images, audio, and text\r | |
12 | using some 8-bit character sets to messages.\r | |
13 | \r | |
14 | This module provides an interface to encode and decode both headers and bodies\r | |
15 | with Base64 encoding.\r | |
16 | \r | |
17 | RFC 2045 defines a method for including character set information in an\r | |
18 | `encoded-word' in a header. This method is commonly used for 8-bit real names\r | |
19 | in To:, From:, Cc:, etc. fields, as well as Subject: lines.\r | |
20 | \r | |
21 | This module does not do the line wrapping or end-of-line character conversion\r | |
22 | necessary for proper internationalized headers; it only does dumb encoding and\r | |
23 | decoding. To deal with the various line wrapping issues, use the email.header\r | |
24 | module.\r | |
25 | """\r | |
26 | \r | |
27 | __all__ = [\r | |
28 | 'base64_len',\r | |
29 | 'body_decode',\r | |
30 | 'body_encode',\r | |
31 | 'decode',\r | |
32 | 'decodestring',\r | |
33 | 'encode',\r | |
34 | 'encodestring',\r | |
35 | 'header_encode',\r | |
36 | ]\r | |
37 | \r | |
38 | \r | |
39 | from binascii import b2a_base64, a2b_base64\r | |
40 | from email.utils import fix_eols\r | |
41 | \r | |
42 | CRLF = '\r\n'\r | |
43 | NL = '\n'\r | |
44 | EMPTYSTRING = ''\r | |
45 | \r | |
46 | # See also Charset.py\r | |
47 | MISC_LEN = 7\r | |
48 | \r | |
49 | \r | |
50 | \f\r | |
51 | # Helpers\r | |
52 | def base64_len(s):\r | |
53 | """Return the length of s when it is encoded with base64."""\r | |
54 | groups_of_3, leftover = divmod(len(s), 3)\r | |
55 | # 4 bytes out for each 3 bytes (or nonzero fraction thereof) in.\r | |
56 | # Thanks, Tim!\r | |
57 | n = groups_of_3 * 4\r | |
58 | if leftover:\r | |
59 | n += 4\r | |
60 | return n\r | |
61 | \r | |
62 | \r | |
63 | \f\r | |
64 | def header_encode(header, charset='iso-8859-1', keep_eols=False,\r | |
65 | maxlinelen=76, eol=NL):\r | |
66 | """Encode a single header line with Base64 encoding in a given charset.\r | |
67 | \r | |
68 | Defined in RFC 2045, this Base64 encoding is identical to normal Base64\r | |
69 | encoding, except that each line must be intelligently wrapped (respecting\r | |
70 | the Base64 encoding), and subsequent lines must start with a space.\r | |
71 | \r | |
72 | charset names the character set to use to encode the header. It defaults\r | |
73 | to iso-8859-1.\r | |
74 | \r | |
75 | End-of-line characters (\\r, \\n, \\r\\n) will be automatically converted\r | |
76 | to the canonical email line separator \\r\\n unless the keep_eols\r | |
77 | parameter is True (the default is False).\r | |
78 | \r | |
79 | Each line of the header will be terminated in the value of eol, which\r | |
80 | defaults to "\\n". Set this to "\\r\\n" if you are using the result of\r | |
81 | this function directly in email.\r | |
82 | \r | |
83 | The resulting string will be in the form:\r | |
84 | \r | |
85 | "=?charset?b?WW/5ciBtYXp66XLrIHf8eiBhIGhhbXBzdGHuciBBIFlv+XIgbWF6euly?=\\n\r | |
86 | =?charset?b?6yB3/HogYSBoYW1wc3Rh7nIgQkMgWW/5ciBtYXp66XLrIHf8eiBhIGhh?="\r | |
87 | \r | |
88 | with each line wrapped at, at most, maxlinelen characters (defaults to 76\r | |
89 | characters).\r | |
90 | """\r | |
91 | # Return empty headers unchanged\r | |
92 | if not header:\r | |
93 | return header\r | |
94 | \r | |
95 | if not keep_eols:\r | |
96 | header = fix_eols(header)\r | |
97 | \r | |
98 | # Base64 encode each line, in encoded chunks no greater than maxlinelen in\r | |
99 | # length, after the RFC chrome is added in.\r | |
100 | base64ed = []\r | |
101 | max_encoded = maxlinelen - len(charset) - MISC_LEN\r | |
102 | max_unencoded = max_encoded * 3 // 4\r | |
103 | \r | |
104 | for i in range(0, len(header), max_unencoded):\r | |
105 | base64ed.append(b2a_base64(header[i:i+max_unencoded]))\r | |
106 | \r | |
107 | # Now add the RFC chrome to each encoded chunk\r | |
108 | lines = []\r | |
109 | for line in base64ed:\r | |
110 | # Ignore the last character of each line if it is a newline\r | |
111 | if line.endswith(NL):\r | |
112 | line = line[:-1]\r | |
113 | # Add the chrome\r | |
114 | lines.append('=?%s?b?%s?=' % (charset, line))\r | |
115 | # Glue the lines together and return it. BAW: should we be able to\r | |
116 | # specify the leading whitespace in the joiner?\r | |
117 | joiner = eol + ' '\r | |
118 | return joiner.join(lines)\r | |
119 | \r | |
120 | \r | |
121 | \f\r | |
122 | def encode(s, binary=True, maxlinelen=76, eol=NL):\r | |
123 | """Encode a string with base64.\r | |
124 | \r | |
125 | Each line will be wrapped at, at most, maxlinelen characters (defaults to\r | |
126 | 76 characters).\r | |
127 | \r | |
128 | If binary is False, end-of-line characters will be converted to the\r | |
129 | canonical email end-of-line sequence \\r\\n. Otherwise they will be left\r | |
130 | verbatim (this is the default).\r | |
131 | \r | |
132 | Each line of encoded text will end with eol, which defaults to "\\n". Set\r | |
133 | this to "\r\n" if you will be using the result of this function directly\r | |
134 | in an email.\r | |
135 | """\r | |
136 | if not s:\r | |
137 | return s\r | |
138 | \r | |
139 | if not binary:\r | |
140 | s = fix_eols(s)\r | |
141 | \r | |
142 | encvec = []\r | |
143 | max_unencoded = maxlinelen * 3 // 4\r | |
144 | for i in range(0, len(s), max_unencoded):\r | |
145 | # BAW: should encode() inherit b2a_base64()'s dubious behavior in\r | |
146 | # adding a newline to the encoded string?\r | |
147 | enc = b2a_base64(s[i:i + max_unencoded])\r | |
148 | if enc.endswith(NL) and eol != NL:\r | |
149 | enc = enc[:-1] + eol\r | |
150 | encvec.append(enc)\r | |
151 | return EMPTYSTRING.join(encvec)\r | |
152 | \r | |
153 | \r | |
154 | # For convenience and backwards compatibility w/ standard base64 module\r | |
155 | body_encode = encode\r | |
156 | encodestring = encode\r | |
157 | \r | |
158 | \r | |
159 | \f\r | |
160 | def decode(s, convert_eols=None):\r | |
161 | """Decode a raw base64 string.\r | |
162 | \r | |
163 | If convert_eols is set to a string value, all canonical email linefeeds,\r | |
164 | e.g. "\\r\\n", in the decoded text will be converted to the value of\r | |
165 | convert_eols. os.linesep is a good choice for convert_eols if you are\r | |
166 | decoding a text attachment.\r | |
167 | \r | |
168 | This function does not parse a full MIME header value encoded with\r | |
169 | base64 (like =?iso-8895-1?b?bmloISBuaWgh?=) -- please use the high\r | |
170 | level email.header class for that functionality.\r | |
171 | """\r | |
172 | if not s:\r | |
173 | return s\r | |
174 | \r | |
175 | dec = a2b_base64(s)\r | |
176 | if convert_eols:\r | |
177 | return dec.replace(CRLF, convert_eols)\r | |
178 | return dec\r | |
179 | \r | |
180 | \r | |
181 | # For convenience and backwards compatibility w/ standard base64 module\r | |
182 | body_decode = decode\r | |
183 | decodestring = decode\r |