mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-01 23:32:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Copy io documentation back from py3k branch so changes can be merged into it.

Browse source
This commit is contained in:
Benjamin Peterson 2008-04-19 19:34:05 +00:00
parent e941d97d12
commit 53be57e8f8
1 changed files with 30 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

55
Doc/library/io.rst
View file

@ -34,7 +34,7 @@ a buffered text interface to a buffered raw stream (:class:`BufferedIOBase`).
Finally, :class:`StringIO` is a in-memory stream for text. Finally, :class:`StringIO` is a in-memory stream for text.
Argument names are not part of the specification, and only the arguments of Argument names are not part of the specification, and only the arguments of
:func:`open()` are intended to be used as keyword arguments. :func:`open` are intended to be used as keyword arguments.
Module Interface Module Interface
@ -43,7 +43,7 @@ Module Interface
.. data:: DEFAULT_BUFFER_SIZE .. data:: DEFAULT_BUFFER_SIZE
An int containing the default buffer size used by the module's buffered I/O An int containing the default buffer size used by the module's buffered I/O
classes. :func:`open()` uses the file's blksize (as obtained by classes. :func:`open` uses the file's blksize (as obtained by
:func:`os.stat`) if possible. :func:`os.stat`) if possible.
.. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]]) .. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])
@ -101,13 +101,14 @@ Module Interface
dependent, but any encoding supported by Python can be passed. See the dependent, but any encoding supported by Python can be passed. See the
:mod:`codecs` module for the list of supported encodings. :mod:`codecs` module for the list of supported encodings.
*errors* is an optional string that specifies how encoding errors are to be *errors* is an optional string that specifies how encoding and decoding
handled---this argument should not be used in binary mode. Pass ``'strict'`` errors are to be handled---this argument should not be used in binary mode.
to raise a :exc:`ValueError` exception if there is an encoding error (the Pass ``'strict'`` to raise a :exc:`ValueError` exception if there is an
default of ``None`` has the same effect), or pass ``'ignore'`` to ignore encoding error (the default of ``None`` has the same effect), or pass
errors. (Note that ignoring encoding errors can lead to data loss.) See the ``'ignore'`` to ignore errors. (Note that ignoring encoding errors can lead
documentation for :func:`codecs.register` for a list of the permitted to data loss.) ``'replace'`` causes a replacement marker (such as ``'?'``)
encoding error strings. to be inserted where there is malformed data. For all possible values, see
:func:`codecs.register`.
*newline* controls how universal newlines works (it only applies to text *newline* controls how universal newlines works (it only applies to text
mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It
@ -131,15 +132,14 @@ Module Interface
when the file is closed. This does not work when a file name is given and when the file is closed. This does not work when a file name is given and
must be ``True`` in that case. must be ``True`` in that case.
:func:`open()` returns a file object whose type depends on the mode, and :func:`open` returns a file object whose type depends on the mode, and
through which the standard file operations such as reading and writing are through which the standard file operations such as reading and writing are
performed. When :func:`open()` is used to open a file in a text mode performed. When :func:`open` is used to open a file in a text mode (``'w'``,
(``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a :class:`TextIOWrapper`.
:class:`TextIOWrapper`. When used to open a file in a binary mode, the When used to open a file in a binary mode, the returned class varies: in read
returned class varies: in read binary mode, it returns a binary mode, it returns a :class:`BufferedReader`; in write binary and append
:class:`BufferedReader`; in write binary and append binary modes, it returns binary modes, it returns a :class:`BufferedWriter`, and in read/write mode,
a :class:`BufferedWriter`, and in read/write mode, it returns a it returns a :class:`BufferedRandom`.
:class:`BufferedRandom`.
It is also possible to use a string or bytearray as a file for both reading It is also possible to use a string or bytearray as a file for both reading
and writing. For strings :class:`StringIO` can be used like a file opened in and writing. For strings :class:`StringIO` can be used like a file opened in
@ -221,8 +221,8 @@ I/O Base Classes
.. method:: flush() .. method:: flush()
Flush the write buffers of the stream if applicable. This is not Flush the write buffers of the stream if applicable. This does nothing
implemented for read-only and non-blocking streams. for read-only and non-blocking streams.
.. method:: isatty() .. method:: isatty()
@ -239,7 +239,7 @@ I/O Base Classes
*limit* bytes will be read. *limit* bytes will be read.
The line terminator is always ``b'\n'`` for binary files; for text files, The line terminator is always ``b'\n'`` for binary files; for text files,
the *newlines* argument to :func:`.open()` can be used to select the line the *newlines* argument to :func:`open` can be used to select the line
terminator(s) recognized. terminator(s) recognized.
.. method:: readlines([hint]) .. method:: readlines([hint])
@ -438,17 +438,17 @@ Buffered Streams
.. method:: read1() .. method:: read1()
In :class:`BytesIO`, this is the same as :meth:`read()`. In :class:`BytesIO`, this is the same as :meth:`read`.
.. method:: truncate([pos]) .. method:: truncate([pos])
Truncate the file to at most *pos* bytes. *pos* defaults to the current Truncate the file to at most *pos* bytes. *pos* defaults to the current
stream position, as returned by :meth:`tell()`. stream position, as returned by :meth:`tell`.
.. class:: BufferedReader(raw[, buffer_size]) .. class:: BufferedReader(raw[, buffer_size])
A buffer for a readable, sequential :class:`BaseRawIO` object. It inherits A buffer for a readable, sequential :class:`RawIOBase` object. It inherits
:class:`BufferedIOBase`. :class:`BufferedIOBase`.
The constructor creates a :class:`BufferedReader` for the given readable The constructor creates a :class:`BufferedReader` for the given readable
@ -577,8 +577,13 @@ Text I/O
*encoding* gives the name of the encoding that the stream will be decoded or *encoding* gives the name of the encoding that the stream will be decoded or
encoded with. It defaults to :func:`locale.getpreferredencoding`. encoded with. It defaults to :func:`locale.getpreferredencoding`.
*errors* determines the strictness of encoding and decoding (see the errors *errors* is an optional string that specifies how encoding and decoding
argument of :func:`codecs.register`) and defaults to ``'strict'``. errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError`
exception if there is an encoding error (the default of ``None`` has the same
effect), or pass ``'ignore'`` to ignore errors. (Note that ignoring encoding
errors can lead to data loss.) ``'replace'`` causes a replacement marker
(such as ``'?'``) to be inserted where there is malformed data. For all
possible values see :func:`codecs.register`.
*newline* can be ``None``, ``''``, ``'\n'``, ``'\r'``, or ``'\r\n'``. It *newline* can be ``None``, ``''``, ``'\n'``, ``'\r'``, or ``'\r\n'``. It
controls the handling of line endings. If it is ``None``, universal newlines controls the handling of line endings. If it is ``None``, universal newlines