PageRenderTime 453ms CodeModel.GetById 141ms app.highlight 6ms RepoModel.GetById 160ms app.codeStats 0ms

/Doc/library/binascii.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 178 lines | 113 code | 65 blank | 0 comment | 0 complexity | bbd781974c8f9f1c2bb1f6760e5edb8e MD5 | raw file
  1
  2:mod:`binascii` --- Convert between binary and ASCII
  3====================================================
  4
  5.. module:: binascii
  6   :synopsis: Tools for converting between binary and various ASCII-encoded binary
  7              representations.
  8
  9
 10.. index::
 11   module: uu
 12   module: base64
 13   module: binhex
 14
 15The :mod:`binascii` module contains a number of methods to convert between
 16binary and various ASCII-encoded binary representations. Normally, you will not
 17use these functions directly but use wrapper modules like :mod:`uu`,
 18:mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains
 19low-level functions written in C for greater speed that are used by the
 20higher-level modules.
 21
 22The :mod:`binascii` module defines the following functions:
 23
 24
 25.. function:: a2b_uu(string)
 26
 27   Convert a single line of uuencoded data back to binary and return the binary
 28   data. Lines normally contain 45 (binary) bytes, except for the last line. Line
 29   data may be followed by whitespace.
 30
 31
 32.. function:: b2a_uu(data)
 33
 34   Convert binary data to a line of ASCII characters, the return value is the
 35   converted line, including a newline char. The length of *data* should be at most
 36   45.
 37
 38
 39.. function:: a2b_base64(string)
 40
 41   Convert a block of base64 data back to binary and return the binary data. More
 42   than one line may be passed at a time.
 43
 44
 45.. function:: b2a_base64(data)
 46
 47   Convert binary data to a line of ASCII characters in base64 coding. The return
 48   value is the converted line, including a newline char. The length of *data*
 49   should be at most 57 to adhere to the base64 standard.
 50
 51
 52.. function:: a2b_qp(string[, header])
 53
 54   Convert a block of quoted-printable data back to binary and return the binary
 55   data. More than one line may be passed at a time. If the optional argument
 56   *header* is present and true, underscores will be decoded as spaces.
 57
 58
 59.. function:: b2a_qp(data[, quotetabs, istext, header])
 60
 61   Convert binary data to a line(s) of ASCII characters in quoted-printable
 62   encoding.  The return value is the converted line(s). If the optional argument
 63   *quotetabs* is present and true, all tabs and spaces will be encoded.   If the
 64   optional argument *istext* is present and true, newlines are not encoded but
 65   trailing whitespace will be encoded. If the optional argument *header* is
 66   present and true, spaces will be encoded as underscores per RFC1522. If the
 67   optional argument *header* is present and false, newline characters will be
 68   encoded as well; otherwise linefeed conversion might corrupt the binary data
 69   stream.
 70
 71
 72.. function:: a2b_hqx(string)
 73
 74   Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression.
 75   The string should contain a complete number of binary bytes, or (in case of the
 76   last portion of the binhex4 data) have the remaining bits zero.
 77
 78
 79.. function:: rledecode_hqx(data)
 80
 81   Perform RLE-decompression on the data, as per the binhex4 standard. The
 82   algorithm uses ``0x90`` after a byte as a repeat indicator, followed by a count.
 83   A count of ``0`` specifies a byte value of ``0x90``. The routine returns the
 84   decompressed data, unless data input data ends in an orphaned repeat indicator,
 85   in which case the :exc:`Incomplete` exception is raised.
 86
 87
 88.. function:: rlecode_hqx(data)
 89
 90   Perform binhex4 style RLE-compression on *data* and return the result.
 91
 92
 93.. function:: b2a_hqx(data)
 94
 95   Perform hexbin4 binary-to-ASCII translation and return the resulting string. The
 96   argument should already be RLE-coded, and have a length divisible by 3 (except
 97   possibly the last fragment).
 98
 99
100.. function:: crc_hqx(data, crc)
101
102   Compute the binhex4 crc value of *data*, starting with an initial *crc* and
103   returning the result.
104
105
106.. function:: crc32(data[, crc])
107
108   Compute CRC-32, the 32-bit checksum of data, starting with an initial crc.  This
109   is consistent with the ZIP file checksum.  Since the algorithm is designed for
110   use as a checksum algorithm, it is not suitable for use as a general hash
111   algorithm.  Use as follows::
112
113      print binascii.crc32("hello world")
114      # Or, in two pieces:
115      crc = binascii.crc32("hello")
116      crc = binascii.crc32(" world", crc) & 0xffffffff
117      print 'crc32 = 0x%08x' % crc
118
119.. note::
120   To generate the same numeric value across all Python versions and
121   platforms use crc32(data) & 0xffffffff.  If you are only using
122   the checksum in packed binary format this is not necessary as the
123   return value is the correct 32bit binary representation
124   regardless of sign.
125
126.. versionchanged:: 2.6
127   The return value is in the range [-2**31, 2**31-1]
128   regardless of platform.  In the past the value would be signed on
129   some platforms and unsigned on others.  Use & 0xffffffff on the
130   value if you want it to match 3.0 behavior.
131
132.. versionchanged:: 3.0
133   The return value is unsigned and in the range [0, 2**32-1]
134   regardless of platform.
135
136
137.. function:: b2a_hex(data)
138              hexlify(data)
139
140   Return the hexadecimal representation of the binary *data*.  Every byte of
141   *data* is converted into the corresponding 2-digit hex representation.  The
142   resulting string is therefore twice as long as the length of *data*.
143
144
145.. function:: a2b_hex(hexstr)
146              unhexlify(hexstr)
147
148   Return the binary data represented by the hexadecimal string *hexstr*.  This
149   function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number
150   of hexadecimal digits (which can be upper or lower case), otherwise a
151   :exc:`TypeError` is raised.
152
153
154.. exception:: Error
155
156   Exception raised on errors. These are usually programming errors.
157
158
159.. exception:: Incomplete
160
161   Exception raised on incomplete data. These are usually not programming errors,
162   but may be handled by reading a little more data and trying again.
163
164
165.. seealso::
166
167   Module :mod:`base64`
168      Support for base64 encoding used in MIME email messages.
169
170   Module :mod:`binhex`
171      Support for the binhex format used on the Macintosh.
172
173   Module :mod:`uu`
174      Support for UU encoding used on Unix.
175
176   Module :mod:`quopri`
177      Support for quoted-printable encoding used in MIME email messages.
178