rest25/library/bz2.rst => rest262/library/bz2.rst
9
10
11.. versionadded:: 2.3
12
13This module provides a comprehensive interface for the bz2 compression library.
14It implements a complete file interface, one-shot (de)compression functions, and
15types for sequential (de)compression.
16
n17+For other archive formats, see the :mod:`gzip`, :mod:`zipfile`, and
18+:mod:`tarfile` modules.
19+ 
17-Here is a resume of the features offered by the bz2 module:
20+Here is a summary of the features offered by the bz2 module:
18
19* :class:`BZ2File` class implements a complete file interface, including
20  :meth:`readline`, :meth:`readlines`, :meth:`writelines`, :meth:`seek`, etc;
21
22* :class:`BZ2File` class implements emulated :meth:`seek` support;
23
24* :class:`BZ2File` class implements universal newline support;
25
27  algorithm borrowed from file objects;
28
29* Sequential (de)compression supported by :class:`BZ2Compressor` and
30  :class:`BZ2Decompressor` classes;
31
32* One-shot (de)compression supported by :func:`compress` and :func:`decompress`
33  functions;
34
n35-* Thread safety uses individual locking mechanism;
n38+* Thread safety uses individual locking mechanism.
36- 
37-* Complete inline documentation;
38
39
40(De)compression of files
41------------------------
42
43Handling of compressed files is offered by the :class:`BZ2File` class.
44
45
46.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
47
n48-   Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading  (default)
n49+   Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
49   or writing. When opened for writing, the file will be created if it doesn't
n50-   exist, and truncated otherwise. If *buffering* is given, ``0`` means unbuffered,
n51+   exist, and truncated otherwise. If *buffering* is given, ``0`` means
51-   and larger numbers specify the buffer size; the default is ``0``. If
52+   unbuffered, and larger numbers specify the buffer size; the default is
52-   *compresslevel* is given, it must be a number between ``1`` and ``9``; the
53+   ``0``. If *compresslevel* is given, it must be a number between ``1`` and
53-   default is ``9``. Add a ``'U'`` to mode to open the file for input with
54+   ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input
54-   universal newline support. Any line ending in the input file will be seen as a
55+   with universal newline support. Any line ending in the input file will be
55-   ``'\n'`` in Python.  Also, a file so opened gains the attribute
56+   seen as a ``'\n'`` in Python.  Also, a file so opened gains the attribute
56   :attr:`newlines`; the value for this attribute is one of ``None`` (no newline
n57-   read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the newline
n58+   read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the
58-   types seen. Universal newlines are available only when reading. Instances
59+   newline types seen. Universal newlines are available only when
59-   support iteration in the same way as normal :class:`file` instances.
60+   reading. Instances support iteration in the same way as normal :class:`file`
61+   instances.
60
61
n62-.. method:: BZ2File.close()
n64+   .. method:: close()
63
n64-   Close the file. Sets data attribute :attr:`closed` to true. A closed file cannot
n66+      Close the file. Sets data attribute :attr:`closed` to true. A closed file
65-   be used for further I/O operations. :meth:`close` may be called more than once
67+      cannot be used for further I/O operations. :meth:`close` may be called
66-   without error.
68+      more than once without error.
67
68
n69-.. method:: BZ2File.read([size])
n71+   .. method:: read([size])
70
n71-   Read at most *size* uncompressed bytes, returned as a string. If the *size*
n73+      Read at most *size* uncompressed bytes, returned as a string. If the
72-   argument is negative or omitted, read until EOF is reached.
74+      *size* argument is negative or omitted, read until EOF is reached.
73
74
n75-.. method:: BZ2File.readline([size])
n77+   .. method:: readline([size])
76
n77-   Return the next line from the file, as a string, retaining newline. A non-
n79+      Return the next line from the file, as a string, retaining newline. A
78-   negative *size* argument limits the maximum number of bytes to return (an
80+      non-negative *size* argument limits the maximum number of bytes to return
79-   incomplete line may be returned then). Return an empty string at EOF.
81+      (an incomplete line may be returned then). Return an empty string at EOF.
80
81
n82-.. method:: BZ2File.readlines([size])
n84+   .. method:: readlines([size])
83
n84-   Return a list of lines read. The optional *size* argument, if given, is an
n86+      Return a list of lines read. The optional *size* argument, if given, is an
85-   approximate bound on the total number of bytes in the lines returned.
87+      approximate bound on the total number of bytes in the lines returned.
86
87
n88-.. method:: BZ2File.xreadlines()
n90+   .. method:: xreadlines()
89
n90-   For backward compatibility. :class:`BZ2File` objects now include the performance
n92+      For backward compatibility. :class:`BZ2File` objects now include the
91-   optimizations previously implemented in the :mod:`xreadlines` module.
93+      performance optimizations previously implemented in the :mod:`xreadlines`
94+      module.
92
n93-   .. deprecated:: 2.3
n96+      .. deprecated:: 2.3
94-      This exists only for compatibility with the method by this name on :class:`file`
97+         This exists only for compatibility with the method by this name on
95-      objects, which is deprecated.  Use ``for line in file`` instead.
98+         :class:`file` objects, which is deprecated.  Use ``for line in file``
99+         instead.
96
97
n98-.. method:: BZ2File.seek(offset[, whence])
n102+   .. method:: seek(offset[, whence])
99
n100-   Move to new file position. Argument *offset* is a byte count. Optional argument
n104+      Move to new file position. Argument *offset* is a byte count. Optional
101-   *whence* defaults to ``0`` (offset from start of file, offset should be ``>=
105+      argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start
102-   0``); other values are ``1`` (move relative to current position, positive or
106+      of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or
103-   negative), and ``2`` (move relative to end of file, usually negative, although
107+      ``1`` (move relative to current position; offset can be positive or
104-   many platforms allow seeking beyond the end of a file).
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).
105
n106-   Note that seeking of bz2 files is emulated, and depending on the parameters the
n112+      Note that seeking of bz2 files is emulated, and depending on the
107-   operation may be extremely slow.
113+      parameters the operation may be extremely slow.
108
109
n110-.. method:: BZ2File.tell()
n116+   .. method:: tell()
111
n112-   Return the current file position, an integer (may be a long integer).
n118+      Return the current file position, an integer (may be a long integer).
113
114
n115-.. method:: BZ2File.write(data)
n121+   .. method:: write(data)
116
n117-   Write string *data* to file. Note that due to buffering, :meth:`close` may be
n123+      Write string *data* to file. Note that due to buffering, :meth:`close` may
118-   needed before the file on disk reflects the data written.
124+      be needed before the file on disk reflects the data written.
119
120
n121-.. method:: BZ2File.writelines(sequence_of_strings)
n127+   .. method:: writelines(sequence_of_strings)
122
n123-   Write the sequence of strings to the file. Note that newlines are not added. The
n129+      Write the sequence of strings to the file. Note that newlines are not
124-   sequence can be any iterable object producing strings. This is equivalent to
130+      added. The sequence can be any iterable object producing strings. This is
125-   calling write() for each string.
131+      equivalent to calling write() for each string.
126
127
128Sequential (de)compression
129--------------------------
130
131Sequential compression and decompression is done using the classes
132:class:`BZ2Compressor` and :class:`BZ2Decompressor`.
133
134
135.. class:: BZ2Compressor([compresslevel])
136
137   Create a new compressor object. This object may be used to compress data
n138-   sequentially. If you want to compress data in one shot, use the :func:`compress`
n144+   sequentially. If you want to compress data in one shot, use the
139-   function instead. The *compresslevel* parameter, if given, must be a number
145+   :func:`compress` function instead. The *compresslevel* parameter, if given,
140-   between ``1`` and ``9``; the default is ``9``.
146+   must be a number between ``1`` and ``9``; the default is ``9``.
141
142
n143-.. method:: BZ2Compressor.compress(data)
n149+   .. method:: compress(data)
144
n145-   Provide more data to the compressor object. It will return chunks of compressed
n151+      Provide more data to the compressor object. It will return chunks of
146-   data whenever possible. When you've finished providing data to compress, call
152+      compressed data whenever possible. When you've finished providing data to
147-   the :meth:`flush` method to finish the compression process, and return what is
153+      compress, call the :meth:`flush` method to finish the compression process,
148-   left in internal buffers.
154+      and return what is left in internal buffers.
149
150
n151-.. method:: BZ2Compressor.flush()
n157+   .. method:: flush()
152
n153-   Finish the compression process and return what is left in internal buffers. You
n159+      Finish the compression process and return what is left in internal
154-   must not use the compressor object after calling this method.
160+      buffers. You must not use the compressor object after calling this method.
155
156
157.. class:: BZ2Decompressor()
158
159   Create a new decompressor object. This object may be used to decompress data
160   sequentially. If you want to decompress data in one shot, use the
161   :func:`decompress` function instead.
162
163
n164-.. method:: BZ2Decompressor.decompress(data)
n170+   .. method:: decompress(data)
165
n166-   Provide more data to the decompressor object. It will return chunks of
n172+      Provide more data to the decompressor object. It will return chunks of
167-   decompressed data whenever possible. If you try to decompress data after the end
173+      decompressed data whenever possible. If you try to decompress data after
168-   of stream is found, :exc:`EOFError` will be raised. If any data was found after
174+      the end of stream is found, :exc:`EOFError` will be raised. If any data
169-   the end of stream, it'll be ignored and saved in :attr:`unused_data` attribute.
175+      was found after the end of stream, it'll be ignored and saved in
176+      :attr:`unused_data` attribute.
170
171
172One-shot (de)compression
173------------------------
174
175One-shot compression and decompression is provided through the :func:`compress`
176and :func:`decompress` functions.
177
178
179.. function:: compress(data[, compresslevel])
180
n181-   Compress *data* in one shot. If you want to compress data sequentially, use an
n188+   Compress *data* in one shot. If you want to compress data sequentially, use
182-   instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, if
189+   an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter,
183-   given, must be a number between ``1`` and ``9``; the default is ``9``.
190+   if given, must be a number between ``1`` and ``9``; the default is ``9``.
184
185
186.. function:: decompress(data)
187
t188-   Decompress *data* in one shot. If you want to decompress data sequentially, use
t195+   Decompress *data* in one shot. If you want to decompress data sequentially,
189-   an instance of :class:`BZ2Decompressor` instead.
196+   use an instance of :class:`BZ2Decompressor` instead.
190
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op