« back to all changes in this revision
Viewing changes to Doc/library/bz2.rst
- browse files at revision 39019
- compare with another revision
- download diff
- download tarball
- view history from revision 39019
- Committer: benjamin.peterson
- Date: 2008-04-25 01:29:10 UTC
- Revision ID: svn-v3-trunk1:6015fed2-1504-0410-9fe1-9d1591cc4771:python%2Ftrunk:62490
reformat some documentation of classes so methods and attributes are under the class directive
- files modified:
- Doc/library/asynchat.rst
added
removed
Doc/library/bz2.rst
46
46
47
47
.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
48
48
49
Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
49
Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
50
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 unbuffered,
52
and larger numbers specify the buffer size; the default is ``0``. If
53
*compresslevel* is given, it must be a number between ``1`` and ``9``; the
54
default is ``9``. Add a ``'U'`` to mode to open the file for input with
55
universal newline support. Any line ending in the input file will be seen as a
56
``'\n'`` in Python. Also, a file so opened gains the attribute
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
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 newline
59
types seen. Universal newlines are available only when reading. Instances
60
support iteration in the same way as normal :class:`file` instances.
61
62
63
.. method:: BZ2File.close()
64
65
Close the file. Sets data attribute :attr:`closed` to true. A closed file cannot
66
be used for further I/O operations. :meth:`close` may be called more than once
67
without error.
68
69
70
.. method:: BZ2File.read([size])
71
72
Read at most *size* uncompressed bytes, returned as a string. If the *size*
73
argument is negative or omitted, read until EOF is reached.
74
75
76
.. method:: BZ2File.readline([size])
77
78
Return the next line from the file, as a string, retaining newline. A
79
non-negative *size* argument limits the maximum number of bytes to return (an
80
incomplete line may be returned then). Return an empty string at EOF.
81
82
83
.. method:: BZ2File.readlines([size])
84
85
Return a list of lines read. The optional *size* argument, if given, is an
86
approximate bound on the total number of bytes in the lines returned.
87
88
89
.. method:: BZ2File.xreadlines()
90
91
For backward compatibility. :class:`BZ2File` objects now include the performance
92
optimizations previously implemented in the :mod:`xreadlines` module.
93
94
.. deprecated:: 2.3
95
This exists only for compatibility with the method by this name on :class:`file`
96
objects, which is deprecated. Use ``for line in file`` instead.
97
98
99
.. method:: BZ2File.seek(offset[, whence])
100
101
Move to new file position. Argument *offset* is a byte count. Optional argument
102
*whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start of file; offset
103
should be ``>= 0``); other values are ``os.SEEK_CUR`` or ``1`` (move relative to
104
current position; offset can be positive or negative), and ``os.SEEK_END`` or
105
``2`` (move relative to end of file; offset is usually negative, although many
106
platforms allow seeking beyond the end of a file).
107
108
Note that seeking of bz2 files is emulated, and depending on the parameters the
109
operation may be extremely slow.
110
111
112
.. method:: BZ2File.tell()
113
114
Return the current file position, an integer (may be a long integer).
115
116
117
.. method:: BZ2File.write(data)
118
119
Write string *data* to file. Note that due to buffering, :meth:`close` may be
120
needed before the file on disk reflects the data written.
121
122
123
.. method:: BZ2File.writelines(sequence_of_strings)
124
125
Write the sequence of strings to the file. Note that newlines are not added. The
126
sequence can be any iterable object producing strings. This is equivalent to
127
calling write() for each string.
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.
128
132
129
133
130
134
Sequential (de)compression
137
141
.. class:: BZ2Compressor([compresslevel])
138
142
139
143
Create a new compressor object. This object may be used to compress data
140
sequentially. If you want to compress data in one shot, use the :func:`compress`
141
function instead. The *compresslevel* parameter, if given, must be a number
142
between ``1`` and ``9``; the default is ``9``.
143
144
145
.. method:: BZ2Compressor.compress(data)
146
147
Provide more data to the compressor object. It will return chunks of compressed
148
data whenever possible. When you've finished providing data to compress, call
149
the :meth:`flush` method to finish the compression process, and return what is
150
left in internal buffers.
151
152
153
.. method:: BZ2Compressor.flush()
154
155
Finish the compression process and return what is left in internal buffers. You
156
must not use the compressor object after calling this method.
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.
157
161
158
162
159
163
.. class:: BZ2Decompressor()
163
167
:func:`decompress` function instead.
164
168
165
169
166
.. method:: BZ2Decompressor.decompress(data)
170
.. method:: decompress(data)
167
171
168
Provide more data to the decompressor object. It will return chunks of
169
decompressed data whenever possible. If you try to decompress data after the end
170
of stream is found, :exc:`EOFError` will be raised. If any data was found after
171
the end of stream, it'll be ignored and saved in :attr:`unused_data` attribute.
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.
172
177
173
178
174
179
One-shot (de)compression
180
185
181
186
.. function:: compress(data[, compresslevel])
182
187
183
Compress *data* in one shot. If you want to compress data sequentially, use an
184
instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, if
185
given, must be a number between ``1`` and ``9``; the default is ``9``.
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``.
186
191
187
192
188
193
.. function:: decompress(data)
189
194
190
Decompress *data* in one shot. If you want to decompress data sequentially, use
191
an instance of :class:`BZ2Decompressor` instead.
195
Decompress *data* in one shot. If you want to decompress data sequentially,
196
use an instance of :class:`BZ2Decompressor` instead.
192
197
Loggerhead is a web-based interface for Breezy
Version: 2.0.1