[Python-3000-checkins] r62307 - in python/branches/py3k: Doc/library/io.rst Lib/io.py

[Georg Brandl]

benjamin.peterson schrieb:
> Author: benjamin.peterson
> Date: Sun Apr 13 02:27:46 2008
> New Revision: 62307
> 
> Log:
> Fleshed out docstrings in the io module, improving the reST one as I went.
> 
> 
> Modified:
>    python/branches/py3k/Doc/library/io.rst
>    python/branches/py3k/Lib/io.py
> 
> Modified: python/branches/py3k/Doc/library/io.rst
> ==============================================================================
> --- python/branches/py3k/Doc/library/io.rst	(original)
> +++ python/branches/py3k/Doc/library/io.rst	Sun Apr 13 02:27:46 2008
> @@ -27,11 +27,14 @@
>  buffered interface to random access streams.  :class:`BytesIO` is a simple
>  stream of in-memory bytes.
>  
> -Another :class:`IOBase` subclass, :class:`TextIOBase` deals with the encoding
> +Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with the encoding
>  and decoding of streams into text.  :class:`TextIOWrapper`, which extends it, is
>  a buffered text interface to a buffered raw stream (:class:`BufferedIOBase`).
>  Finally, :class:`StringIO` is a in-memory stream for text.
>  
> +Argument names are not part of the specification, and only the arguments of
> +:func:`open()` are intended to be used as keyword arguments.

Please don't add parentheses in :func:`foo` etc.; they are added
automatically by Sphinx.

>     .. method:: flush()
>  
> -      Flush the write buffers of the stream if applicable.  This is a no-op for
> -      read-only and non-blocking streams.
> +      Flush the write buffers of the stream if applicable.  This is not
> +      implemented for read-only and non-blocking streams.

"Not implemented" is ambiguous -- does it raise an error? Does it do nothing?

> -.. class:: BufferedReader(raw, [buffer_size])
> +.. class:: BufferedReader(raw[, buffer_size])
>  
> -   A buffer for a readable sequential RawIO object.  It inherits
> +   A buffer for a readable, sequential :class:`BaseRawIO` object.  It inherits
>     :class:`BufferedIOBase`.

I guess this means RawIOBase?

>     *errors* determines the strictness of encoding and decoding (see the errors
> -   argument of :func:`codecs.open`) and defaults to "strict".
> +   argument of :func:`codecs.register`) and defaults to ``'strict'``.

The "errors" argument should be documented in this file too.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.