← Back to branch summary

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

« back to all changes in this revision

Viewing changes to Doc/library/bz2.rst

  • 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:
Doc/library/bz2.rst
 
1
 
 
2
:mod:`bz2` --- Compression compatible with :program:`bzip2`
 
3
===========================================================
 
4
 
 
5
.. module:: bz2
 
6
   :synopsis: Interface to compression and decompression routines compatible with bzip2.
 
7
.. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
 
8
.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
 
9
 
 
10
 
 
11
.. versionadded:: 2.3
 
12
 
 
13
This module provides a comprehensive interface for the bz2 compression library.
 
14
It implements a complete file interface, one-shot (de)compression functions, and
 
15
types for sequential (de)compression.
 
16
 
 
17
For other archive formats, see the :mod:`gzip`, :mod:`zipfile`, and
 
18
:mod:`tarfile` modules.
 
19
 
 
20
Here is a summary of the features offered by the bz2 module:
 
21
 
 
22
* :class:`BZ2File` class implements a complete file interface, including
 
23
  :meth:`readline`, :meth:`readlines`, :meth:`writelines`, :meth:`seek`, etc;
 
24
 
 
25
* :class:`BZ2File` class implements emulated :meth:`seek` support;
 
26
 
 
27
* :class:`BZ2File` class implements universal newline support;
 
28
 
 
29
* :class:`BZ2File` class offers an optimized line iteration using the readahead
 
30
  algorithm borrowed from file objects;
 
31
 
 
32
* Sequential (de)compression supported by :class:`BZ2Compressor` and
 
33
  :class:`BZ2Decompressor` classes;
 
34
 
 
35
* One-shot (de)compression supported by :func:`compress` and :func:`decompress`
 
36
  functions;
 
37
 
 
38
* Thread safety uses individual locking mechanism.
 
39
 
 
40
 
 
41
(De)compression of files
 
42
------------------------
 
43
 
 
44
Handling of compressed files is offered by the :class:`BZ2File` class.
 
45
 
 
46
 
 
47
.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
 
48
 
 
49
   Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
 
50
   or writing. When opened for writing, the file will be created if it doesn't
 
51
   exist, and truncated otherwise. If *buffering* is given, ``0`` means
 
52
   unbuffered, and larger numbers specify the buffer size; the default is
 
53
   ``0``. If *compresslevel* is given, it must be a number between ``1`` and
 
54
   ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input
 
55
   with universal newline support. Any line ending in the input file will be
 
56
   seen as a ``'\n'`` in Python.  Also, a file so opened gains the attribute
 
57
   :attr:`newlines`; the value for this attribute is one of ``None`` (no newline
 
58
   read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the
 
59
   newline types seen. Universal newlines are available only when
 
60
   reading. Instances support iteration in the same way as normal :class:`file`
 
61
   instances.
 
62
 
 
63
 
 
64
   .. method:: close()
 
65
 
 
66
      Close the file. Sets data attribute :attr:`closed` to true. A closed file
 
67
      cannot be used for further I/O operations. :meth:`close` may be called
 
68
      more than once without error.
 
69
 
 
70
 
 
71
   .. method:: read([size])
 
72
 
 
73
      Read at most *size* uncompressed bytes, returned as a string. If the
 
74
      *size* argument is negative or omitted, read until EOF is reached.
 
75
 
 
76
 
 
77
   .. method:: readline([size])
 
78
 
 
79
      Return the next line from the file, as a string, retaining newline. A
 
80
      non-negative *size* argument limits the maximum number of bytes to return
 
81
      (an incomplete line may be returned then). Return an empty string at EOF.
 
82
 
 
83
 
 
84
   .. method:: readlines([size])
 
85
 
 
86
      Return a list of lines read. The optional *size* argument, if given, is an
 
87
      approximate bound on the total number of bytes in the lines returned.
 
88
 
 
89
 
 
90
   .. method:: xreadlines()
 
91
 
 
92
      For backward compatibility. :class:`BZ2File` objects now include the
 
93
      performance optimizations previously implemented in the :mod:`xreadlines`
 
94
      module.
 
95
 
 
96
      .. deprecated:: 2.3 
 
97
         This exists only for compatibility with the method by this name on
 
98
         :class:`file` objects, which is deprecated.  Use ``for line in file``
 
99
         instead.
 
100
 
 
101
 
 
102
   .. method:: seek(offset[, whence])
 
103
 
 
104
      Move to new file position. Argument *offset* is a byte count. Optional
 
105
      argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start
 
106
      of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or
 
107
      ``1`` (move relative to current position; offset can be positive or
 
108
      negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file;
 
109
      offset is usually negative, although many platforms allow seeking beyond
 
110
      the end of a file).
 
111
 
 
112
      Note that seeking of bz2 files is emulated, and depending on the
 
113
      parameters the operation may be extremely slow.
 
114
 
 
115
 
 
116
   .. method:: tell()
 
117
 
 
118
      Return the current file position, an integer (may be a long integer).
 
119
 
 
120
 
 
121
   .. method:: write(data)
 
122
 
 
123
      Write string *data* to file. Note that due to buffering, :meth:`close` may
 
124
      be needed before the file on disk reflects the data written.
 
125
 
 
126
 
 
127
   .. method:: writelines(sequence_of_strings)
 
128
 
 
129
      Write the sequence of strings to the file. Note that newlines are not
 
130
      added. The sequence can be any iterable object producing strings. This is
 
131
      equivalent to calling write() for each string.
 
132
 
 
133
 
 
134
Sequential (de)compression
 
135
--------------------------
 
136
 
 
137
Sequential compression and decompression is done using the classes
 
138
:class:`BZ2Compressor` and :class:`BZ2Decompressor`.
 
139
 
 
140
 
 
141
.. class:: BZ2Compressor([compresslevel])
 
142
 
 
143
   Create a new compressor object. This object may be used to compress data
 
144
   sequentially. If you want to compress data in one shot, use the
 
145
   :func:`compress` function instead. The *compresslevel* parameter, if given,
 
146
   must be a number between ``1`` and ``9``; the default is ``9``.
 
147
 
 
148
 
 
149
   .. method:: compress(data)
 
150
 
 
151
      Provide more data to the compressor object. It will return chunks of
 
152
      compressed data whenever possible. When you've finished providing data to
 
153
      compress, call the :meth:`flush` method to finish the compression process,
 
154
      and return what is left in internal buffers.
 
155
 
 
156
 
 
157
   .. method:: flush()
 
158
 
 
159
      Finish the compression process and return what is left in internal
 
160
      buffers. You must not use the compressor object after calling this method.
 
161
 
 
162
 
 
163
.. class:: BZ2Decompressor()
 
164
 
 
165
   Create a new decompressor object. This object may be used to decompress data
 
166
   sequentially. If you want to decompress data in one shot, use the
 
167
   :func:`decompress` function instead.
 
168
 
 
169
 
 
170
   .. method:: decompress(data)
 
171
 
 
172
      Provide more data to the decompressor object. It will return chunks of
 
173
      decompressed data whenever possible. If you try to decompress data after
 
174
      the end of stream is found, :exc:`EOFError` will be raised. If any data
 
175
      was found after the end of stream, it'll be ignored and saved in
 
176
      :attr:`unused_data` attribute.
 
177
 
 
178
 
 
179
One-shot (de)compression
 
180
------------------------
 
181
 
 
182
One-shot compression and decompression is provided through the :func:`compress`
 
183
and :func:`decompress` functions.
 
184
 
 
185
 
 
186
.. function:: compress(data[, compresslevel])
 
187
 
 
188
   Compress *data* in one shot. If you want to compress data sequentially, use
 
189
   an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter,
 
190
   if given, must be a number between ``1`` and ``9``; the default is ``9``.
 
191
 
 
192
 
 
193
.. function:: decompress(data)
 
194
 
 
195
   Decompress *data* in one shot. If you want to decompress data sequentially,
 
196
   use an instance of :class:`BZ2Decompressor` instead.
 
197