← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Lib/email/base64mime.py

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

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