Skip to content

[3.10] gh-85864: io docs: Add missing position-only parameters (GH-91950) #92085

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

Merged
merged 1 commit into from
Apr 30, 2022
Merged

[3.10] gh-85864: io docs: Add missing position-only parameters (GH-91950) #92085

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
34 changes: 17 additions & 17 deletions Doc/library/io.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -396,7 +396,7 @@ I/O Base Classes
Note that it's already possible to iterate on file objects using ``for
line in file: ...`` without calling ``file.readlines()``.

.. method:: seek(offset, whence=SEEK_SET)
.. method:: seek(offset, whence=SEEK_SET, /)

Change the stream position to the given byte *offset*. *offset* is
interpreted relative to the position indicated by *whence*. The default
Expand Down Expand Up @@ -428,7 +428,7 @@ I/O Base Classes

Return the current stream position.

.. method:: truncate(size=None)
.. method:: truncate(size=None, /)

Resize the stream to the given *size* in bytes (or the current position
if *size* is not specified). The current stream position isn't changed.
Expand All @@ -445,7 +445,7 @@ I/O Base Classes
Return ``True`` if the stream supports writing. If ``False``,
:meth:`write` and :meth:`truncate` will raise :exc:`OSError`.

.. method:: writelines(lines)
.. method:: writelines(lines, /)

Write a list of lines to the stream. Line separators are not added, so it
is usual for each of the lines provided to have a line separator at the
Expand Down Expand Up @@ -489,15 +489,15 @@ I/O Base Classes
Read and return all the bytes from the stream until EOF, using multiple
calls to the stream if necessary.

.. method:: readinto(b)
.. 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.

.. method:: write(b)
.. method:: write(b, /)

Write the given :term:`bytes-like object`, *b*, to the
underlying raw stream, and return the number of
Expand Down Expand Up @@ -554,7 +554,7 @@ I/O Base Classes

.. versionadded:: 3.1

.. method:: read(size=-1)
.. method:: read(size=-1, /)

Read and return up to *size* bytes. If the argument is omitted, ``None``,
or negative, data is read and returned until EOF is reached. An empty
Expand All @@ -569,7 +569,7 @@ I/O Base Classes
A :exc:`BlockingIOError` is raised if the underlying raw stream is in
non blocking-mode, and has no data available at the moment.

.. method:: read1([size])
.. method:: read1(size=-1, /)

Read and return up to *size* bytes, with at most one call to the
underlying raw stream's :meth:`~RawIOBase.read` (or
Expand Down Expand Up @@ -604,7 +604,7 @@ I/O Base Classes

.. versionadded:: 3.5

.. method:: write(b)
.. method:: write(b, /)

Write the given :term:`bytes-like object`, *b*, and return the number
of bytes written (always equal to the length of *b* in bytes, since if
Expand Down Expand Up @@ -687,7 +687,7 @@ Buffered Streams
Buffered I/O streams provide a higher-level interface to an I/O device
than raw I/O does.

.. class:: BytesIO([initial_bytes])
.. class:: BytesIO(initial_bytes=b'')

A binary stream using an in-memory bytes buffer. It inherits
:class:`BufferedIOBase`. The buffer is discarded when the
Expand Down Expand Up @@ -722,14 +722,14 @@ than raw I/O does.
Return :class:`bytes` containing the entire contents of the buffer.


.. method:: read1([size], /)
.. method:: read1(size=-1, /)

In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.read`.

.. versionchanged:: 3.7
The *size* argument is now optional.

.. method:: readinto1(b)
.. method:: readinto1(b, /)

In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.readinto`.

Expand All @@ -752,18 +752,18 @@ than raw I/O does.
:class:`BufferedReader` provides or overrides these methods in addition to
those from :class:`BufferedIOBase` and :class:`IOBase`:

.. method:: peek([size])
.. method:: peek(size=0, /)

Return bytes from the stream without advancing the position. At most one
single read on the raw stream is done to satisfy the call. The number of
bytes returned may be less or more than requested.

.. method:: read([size])
.. method:: read(size=-1, /)

Read and return *size* bytes, or if *size* is not given or negative, until
EOF or if the read call would block in non-blocking mode.

.. method:: read1([size])
.. method:: read1(size=-1, /)

Read and return up to *size* bytes with only one call on the raw stream.
If at least one byte is buffered, only buffered bytes are returned.
Expand Down Expand Up @@ -895,14 +895,14 @@ Text I/O
Read and return at most *size* characters from the stream as a single
:class:`str`. If *size* is negative or ``None``, reads until EOF.

.. method:: readline(size=-1)
.. method:: readline(size=-1, /)

Read until newline or EOF and return a single ``str``. If the stream is
already at EOF, an empty string is returned.

If *size* is specified, at most *size* characters will be read.

.. method:: seek(offset, whence=SEEK_SET)
.. method:: seek(offset, whence=SEEK_SET, /)

Change the stream position to the given *offset*. Behaviour depends on
the *whence* parameter. The default value for *whence* is
Expand All @@ -929,7 +929,7 @@ Text I/O
does not usually represent a number of bytes in the underlying
binary storage.

.. method:: write(s)
.. method:: write(s, /)

Write the string *s* to the stream and return the number of characters
written.
Expand Down