Thanks to visit codestin.com
Credit goes to github.com

Skip to content

gh-129011: Update docs for Raw I/O read, readinto, and write #135328

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

gh-129011: Update docs for Raw I/O read, readinto, and write #135328

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 41 additions & 9 deletions Doc/library/io.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ will raise a :exc:`TypeError`. So will giving a :class:`bytes` object to the
Operations that used to raise :exc:`IOError` now raise :exc:`OSError`, since
:exc:`IOError` is now an alias of :exc:`OSError`.

.. _text-io:

Text I/O
^^^^^^^^
Expand Down Expand Up @@ -73,6 +74,7 @@ In-memory text streams are also available as :class:`StringIO` objects::
The text stream API is described in detail in the documentation of
:class:`TextIOBase`.

.. _binary-io:

Binary I/O
^^^^^^^^^^
Expand Down Expand Up @@ -111,6 +113,13 @@ stream by opening a file in binary mode with buffering disabled::

The raw stream API is described in detail in the docs of :class:`RawIOBase`.

.. warning::
Raw I/O is a low-level interface and methods generally must have their return
values checked and be explicitly retried to ensure an operation completes.
For instance :meth:`~RawIOBase.write` returns the number of bytes written
which may be less than the number of bytes provided (a partial write).
High-level I/O objects like :ref:`binary-io` and :ref:`text-io` implement
retry behavior.

.. _io-text-encoding:

Expand Down Expand Up @@ -486,8 +495,11 @@ I/O Base Classes

Read up to *size* bytes from the object and return them. As a convenience,
if *size* is unspecified or -1, all bytes until EOF are returned.
Otherwise, only one system call is ever made. Fewer than *size* bytes may
be returned if the operating system call returns fewer than *size* bytes.

Attempts to make only one system call but will retry if interrupted and
the signal handler does not raise an exception (see :pep:`475` for the
rationale). This means fewer than *size* bytes may be returned if the
operating system call returns fewer than *size* bytes.

If 0 bytes are returned, and *size* was not 0, this indicates end of file.
If the object is in non-blocking mode and no bytes are available,
Expand All @@ -501,13 +513,19 @@ I/O Base Classes
Read and return all the bytes from the stream until EOF, using multiple
calls to the stream if necessary.

If 0 bytes are returned this indicates end of file. If the object is in
non-blocking mode and the underlying :meth:`read` returns ``None``
indicating no bytes are available ``None`` is returned.

.. method:: readinto(b, /)

Read bytes into a pre-allocated, writable
:term:`bytes-like object` *b*, and return the
number of bytes read. For example, *b* might be a :class:`bytearray`.
If the object is in non-blocking mode and no bytes
are available, ``None`` is returned.

If 0 is returned and ``len(b)`` is not 0 this indicates end of file. If
the object is in non-blocking mode and no bytes are available ``None`` is
returned.

.. method:: write(b, /)

Expand All @@ -521,6 +539,13 @@ I/O Base Classes
this method returns, so the implementation should only access *b*
during the method call.

.. warning::

This function does not ensure all bytes are written or an exception is
thrown. Callers may implement that behavior by checking the return
value, and if it is less than the length of *b* looping with additional
write calls until all unwritten bytes are written. High-level I/O
objects like :ref:`binary-io` and :ref:`text-io` implement retry behavior.

.. class:: BufferedIOBase

Expand Down Expand Up @@ -649,7 +674,11 @@ Raw File I/O
.. class:: FileIO(name, mode='r', closefd=True, opener=None)

A raw binary stream representing an OS-level file containing bytes data. It
inherits from :class:`RawIOBase`.
inherits from :class:`RawIOBase` and implements its low-level access design.
This means :meth:`~RawIOBase.write` doesn't guarantee all bytes are written
and :meth:`~RawIOBase.read` may read less bytes than requested even when more
bytes may be present in the underlying file. To get "write all" and
"read at least" behavior use :ref:`binary-io`.

The *name* can be one of two things:

Expand All @@ -669,10 +698,6 @@ Raw File I/O
implies writing, so this mode behaves in a similar way to ``'w'``. Add a
``'+'`` to the mode to allow simultaneous reading and writing.

The :meth:`~RawIOBase.read` (when called with a positive argument),
:meth:`~RawIOBase.readinto` and :meth:`~RawIOBase.write` methods on this
class will only make one system call.

A custom opener can be used by passing a callable as *opener*. The underlying
file descriptor for the file object is then obtained by calling *opener* with
(*name*, *flags*). *opener* must return an open file descriptor (passing
Expand All @@ -684,6 +709,13 @@ Raw File I/O
See the :func:`open` built-in function for examples on using the *opener*
parameter.

.. warning::
:class:`FileIO` is a low-level I/O object and members, such as
:meth:`~RawIOBase.read` and :meth:`~RawIOBase.write`, need to have their
return values checked explicitly in a retry loop to implement "write all"
and "read at least" behavior. High-level I/O objects :ref:`binary-io` and
:ref:`text-io` implement retry behavior.

.. versionchanged:: 3.3
The *opener* parameter was added.
The ``'x'`` mode was added.
Expand Down
Loading