Merged revisions 62490 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r62490 | benjamin.peterson | 2008-04-24 20:29:10 -0500 (Thu, 24 Apr 2008) | 2 lines
reformat some documentation of classes so methods and attributes are under the class directive
........
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index ac1695b..cde5749 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -44,75 +44,77 @@
.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
- Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
+ Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
or writing. When opened for writing, the file will be created if it doesn't
- exist, and truncated otherwise. If *buffering* is given, ``0`` means unbuffered,
- and larger numbers specify the buffer size; the default is ``0``. If
- *compresslevel* is given, it must be a number between ``1`` and ``9``; the
- default is ``9``. Add a ``'U'`` to mode to open the file for input with
- universal newline support. Any line ending in the input file will be seen as a
- ``'\n'`` in Python. Also, a file so opened gains the attribute
+ exist, and truncated otherwise. If *buffering* is given, ``0`` means
+ unbuffered, and larger numbers specify the buffer size; the default is
+ ``0``. If *compresslevel* is given, it must be a number between ``1`` and
+ ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input
+ with universal newline support. Any line ending in the input file will be
+ seen as a ``'\n'`` in Python. Also, a file so opened gains the attribute
:attr:`newlines`; the value for this attribute is one of ``None`` (no newline
- read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the newline
- types seen. Universal newlines are available only when reading. Instances
- support iteration in the same way as normal :class:`file` instances.
+ read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the
+ newline types seen. Universal newlines are available only when
+ reading. Instances support iteration in the same way as normal :class:`file`
+ instances.
-.. method:: BZ2File.close()
+ .. method:: close()
- Close the file. Sets data attribute :attr:`closed` to true. A closed file cannot
- be used for further I/O operations. :meth:`close` may be called more than once
- without error.
+ Close the file. Sets data attribute :attr:`closed` to true. A closed file
+ cannot be used for further I/O operations. :meth:`close` may be called
+ more than once without error.
-.. method:: BZ2File.read([size])
+ .. method:: read([size])
- Read at most *size* uncompressed bytes, returned as a string. If the *size*
- argument is negative or omitted, read until EOF is reached.
+ Read at most *size* uncompressed bytes, returned as a string. If the
+ *size* argument is negative or omitted, read until EOF is reached.
-.. method:: BZ2File.readline([size])
+ .. method:: readline([size])
- Return the next line from the file, as a string, retaining newline. A
- non-negative *size* argument limits the maximum number of bytes to return (an
- incomplete line may be returned then). Return an empty string at EOF.
+ Return the next line from the file, as a string, retaining newline. A
+ non-negative *size* argument limits the maximum number of bytes to return
+ (an incomplete line may be returned then). Return an empty string at EOF.
-.. method:: BZ2File.readlines([size])
+ .. method:: readlines([size])
- Return a list of lines read. The optional *size* argument, if given, is an
- approximate bound on the total number of bytes in the lines returned.
+ Return a list of lines read. The optional *size* argument, if given, is an
+ approximate bound on the total number of bytes in the lines returned.
-.. method:: BZ2File.seek(offset[, whence])
+ .. method:: seek(offset[, whence])
- Move to new file position. Argument *offset* is a byte count. Optional argument
- *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start of file; offset
- should be ``>= 0``); other values are ``os.SEEK_CUR`` or ``1`` (move relative to
- current position; offset can be positive or negative), and ``os.SEEK_END`` or
- ``2`` (move relative to end of file; offset is usually negative, although many
- platforms allow seeking beyond the end of a file).
+ Move to new file position. Argument *offset* is a byte count. Optional
+ argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start
+ of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or
+ ``1`` (move relative to current position; offset can be positive or
+ negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file;
+ offset is usually negative, although many platforms allow seeking beyond
+ the end of a file).
- Note that seeking of bz2 files is emulated, and depending on the parameters the
- operation may be extremely slow.
+ Note that seeking of bz2 files is emulated, and depending on the
+ parameters the operation may be extremely slow.
-.. method:: BZ2File.tell()
+ .. method:: tell()
- Return the current file position, an integer.
+ Return the current file position, an integer.
-.. method:: BZ2File.write(data)
+ .. method:: write(data)
- Write string *data* to file. Note that due to buffering, :meth:`close` may be
- needed before the file on disk reflects the data written.
+ Write string *data* to file. Note that due to buffering, :meth:`close` may
+ be needed before the file on disk reflects the data written.
-.. method:: BZ2File.writelines(sequence_of_strings)
+ .. method:: writelines(sequence_of_strings)
- Write the sequence of strings to the file. Note that newlines are not added. The
- sequence can be any iterable object producing strings. This is equivalent to
- calling write() for each string.
+ Write the sequence of strings to the file. Note that newlines are not
+ added. The sequence can be any iterable object producing strings. This is
+ equivalent to calling write() for each string.
Sequential (de)compression
@@ -125,23 +127,23 @@
.. class:: BZ2Compressor([compresslevel])
Create a new compressor object. This object may be used to compress data
- sequentially. If you want to compress data in one shot, use the :func:`compress`
- function instead. The *compresslevel* parameter, if given, must be a number
- between ``1`` and ``9``; the default is ``9``.
+ sequentially. If you want to compress data in one shot, use the
+ :func:`compress` function instead. The *compresslevel* parameter, if given,
+ must be a number between ``1`` and ``9``; the default is ``9``.
-.. method:: BZ2Compressor.compress(data)
+ .. method:: compress(data)
- Provide more data to the compressor object. It will return chunks of compressed
- data whenever possible. When you've finished providing data to compress, call
- the :meth:`flush` method to finish the compression process, and return what is
- left in internal buffers.
+ Provide more data to the compressor object. It will return chunks of
+ compressed data whenever possible. When you've finished providing data to
+ compress, call the :meth:`flush` method to finish the compression process,
+ and return what is left in internal buffers.
-.. method:: BZ2Compressor.flush()
+ .. method:: flush()
- Finish the compression process and return what is left in internal buffers. You
- must not use the compressor object after calling this method.
+ Finish the compression process and return what is left in internal
+ buffers. You must not use the compressor object after calling this method.
.. class:: BZ2Decompressor()
@@ -151,12 +153,13 @@
:func:`decompress` function instead.
-.. method:: BZ2Decompressor.decompress(data)
+ .. method:: decompress(data)
- Provide more data to the decompressor object. It will return chunks of
- decompressed data whenever possible. If you try to decompress data after the end
- of stream is found, :exc:`EOFError` will be raised. If any data was found after
- the end of stream, it'll be ignored and saved in :attr:`unused_data` attribute.
+ Provide more data to the decompressor object. It will return chunks of
+ decompressed data whenever possible. If you try to decompress data after
+ the end of stream is found, :exc:`EOFError` will be raised. If any data
+ was found after the end of stream, it'll be ignored and saved in
+ :attr:`unused_data` attribute.
One-shot (de)compression
@@ -168,13 +171,13 @@
.. function:: compress(data[, compresslevel])
- Compress *data* in one shot. If you want to compress data sequentially, use an
- instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, if
- given, must be a number between ``1`` and ``9``; the default is ``9``.
+ Compress *data* in one shot. If you want to compress data sequentially, use
+ an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter,
+ if given, must be a number between ``1`` and ``9``; the default is ``9``.
.. function:: decompress(data)
- Decompress *data* in one shot. If you want to decompress data sequentially, use
- an instance of :class:`BZ2Decompressor` instead.
+ Decompress *data* in one shot. If you want to decompress data sequentially,
+ use an instance of :class:`BZ2Decompressor` instead.