[3.11] gh-101100: Fix Sphinx warnings for `fileno` (GH-111118) (#111227)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index d03f2c4f0ca97a61ba937395139c99add2a4bcef..51b1da89683eadd582da33eb3d4b3bdbc1629f24 100644 (file)
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -91,7 +91,7 @@ The :mod:`bz2` module contains:
    and :meth:`~io.IOBase.truncate`.
    Iteration and the :keyword:`with` statement are supported.
 
-   :class:`BZ2File` also provides the following method:
+   :class:`BZ2File` also provides the following methods:
 
    .. method:: peek([n])
 
@@ -106,14 +106,52 @@ The :mod:`bz2` module contains:
 
       .. versionadded:: 3.3
 
+   .. method:: fileno()
+
+      Return the file descriptor for the underlying file.
+
+      .. versionadded:: 3.3
+
+   .. method:: readable()
+
+      Return whether the file was opened for reading.
+
+      .. versionadded:: 3.3
+
+   .. method:: seekable()
+
+      Return whether the file supports seeking.
+
+      .. versionadded:: 3.3
+
+   .. method:: writable()
+
+      Return whether the file was opened for writing.
+
+      .. versionadded:: 3.3
+
+   .. method:: read1(size=-1)
+
+      Read up to *size* uncompressed bytes, while trying to avoid
+      making multiple reads from the underlying stream. Reads up to a
+      buffer's worth of data if size is negative.
+
+      Returns ``b''`` if the file is at EOF.
+
+      .. versionadded:: 3.3
+
+   .. method:: readinto(b)
+
+      Read bytes into *b*.
+
+      Returns the number of bytes read (0 for EOF).
+
+      .. versionadded:: 3.3
+
 
    .. versionchanged:: 3.1
       Support for the :keyword:`with` statement was added.
 
-   .. versionchanged:: 3.3
-      The :meth:`fileno`, :meth:`readable`, :meth:`seekable`, :meth:`writable`,
-      :meth:`read1` and :meth:`readinto` methods were added.
-
    .. versionchanged:: 3.3
       Support was added for *filename* being a :term:`file object` instead of an
       actual filename.

diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst
index c4f8781f2ac9936e79339c0ea332719932c2004b..21fa97a2a3cef8e61b946e68f1dc07d4b746fbae 100644 (file)
--- a/Doc/library/mmap.rst
+++ b/Doc/library/mmap.rst
@@ -19,7 +19,7 @@ the current file position, and :meth:`seek` through the file to different positi
 A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is
 different on Unix and on Windows.  In either case you must provide a file
 descriptor for a file opened for update. If you wish to map an existing Python
-file object, use its :meth:`fileno` method to obtain the correct value for the
+file object, use its :meth:`~io.IOBase.fileno` method to obtain the correct value for the
 *fileno* parameter.  Otherwise, you can open the file using the
 :func:`os.open` function, which returns a file descriptor directly (the file
 still needs to be closed when done).

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 2162328be9adb27c43f14abf61b5d1c7e31ceced..99dda5b5768fbd0e0af6766a0d5ceeb708db33ce 100644 (file)
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -2540,7 +2540,7 @@ multiple connections at the same time.
    **Windows**: An item in *object_list* must either be an integer
    handle which is waitable (according to the definition used by the
    documentation of the Win32 function ``WaitForMultipleObjects()``)
-   or it can be an object with a :meth:`fileno` method which returns a
+   or it can be an object with a :meth:`~io.IOBase.fileno` method which returns a
    socket handle or pipe handle.  (Note that pipe handles and socket
    handles are **not** waitable handles.)
 

diff --git a/Doc/library/selectors.rst b/Doc/library/selectors.rst
index dd50bac37e49b88086fe91d84975f9462e8092c1..76cbf91412f763329be3474328afed8eb946676e 100644 (file)
--- a/Doc/library/selectors.rst
+++ b/Doc/library/selectors.rst
@@ -21,7 +21,7 @@ It defines a :class:`BaseSelector` abstract base class, along with several
 concrete implementations (:class:`KqueueSelector`, :class:`EpollSelector`...),
 that can be used to wait for I/O readiness notification on multiple file
 objects. In the following, "file object" refers to any object with a
-:meth:`fileno()` method, or a raw file descriptor. See :term:`file object`.
+:meth:`~io.IOBase.fileno` method, or a raw file descriptor. See :term:`file object`.
 
 :class:`DefaultSelector` is an alias to the most efficient implementation
 available on the current platform: this should be the default choice for most

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index c7274f59f43d1a5871d34d908ce9b6a9d335e857..7193713984f169949530c8ab9aced8c2a98ce32a 100644 (file)
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -759,7 +759,7 @@ The following functions all create :ref:`socket objects <socket-objects>`.
 .. function:: fromfd(fd, family, type, proto=0)
 
    Duplicate the file descriptor *fd* (an integer as returned by a file object's
-   :meth:`fileno` method) and build a socket object from the result.  Address
+   :meth:`~io.IOBase.fileno` method) and build a socket object from the result.  Address
    family, socket type and protocol number are as for the :func:`.socket` function
    above. The file descriptor should refer to a socket, but this is not checked ---
    subsequent operations on the object may fail if the file descriptor is invalid.

diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
index 84a6f8887954ccf4a3f033af00e864b6b4314cc4..54096f083fd98b25642fe378ae31efafcb3a32ca 100644 (file)
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -103,7 +103,7 @@ The module defines the following user-callable items:
 
    This class operates exactly as :func:`TemporaryFile` does, except that
    data is spooled in memory until the file size exceeds *max_size*, or
-   until the file's :func:`fileno` method is called, at which point the
+   until the file's :func:`~io.IOBase.fileno` method is called, at which point the
    contents are written to disk and operation proceeds as with
    :func:`TemporaryFile`.
 

diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 8fd7bcab8b2dffa3ba98adce54e81a6fcfcd0300..5dc8bdc61f6ce56298949fa27bae9d210bec4eaa 100644 (file)
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -39,7 +39,6 @@ Doc/library/asyncio-subprocess.rst
 Doc/library/asyncio-task.rst
 Doc/library/bdb.rst
 Doc/library/bisect.rst
-Doc/library/bz2.rst
 Doc/library/calendar.rst
 Doc/library/cmd.rst
 Doc/library/collections.abc.rst
@@ -104,7 +103,6 @@ Doc/library/reprlib.rst
 Doc/library/resource.rst
 Doc/library/rlcompleter.rst
 Doc/library/select.rst
-Doc/library/selectors.rst
 Doc/library/shelve.rst
 Doc/library/signal.rst
 Doc/library/smtplib.rst

diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
index ad0931ecbed060091f8ba54645b3a6ec37c17590..3608153db073a6f05ff2e3b854346c79da5fb98a 100644 (file)
--- a/Doc/whatsnew/2.5.rst
+++ b/Doc/whatsnew/2.5.rst
@@ -1347,7 +1347,7 @@ complete list of changes, or look through the SVN logs for all the details.
   :func:`input` function to allow opening files in binary or :term:`universal
   newlines` mode.  Another new parameter, *openhook*, lets you use a function
   other than :func:`open`  to open the input files.  Once you're iterating over
-  the set of files, the :class:`FileInput` object's new :meth:`fileno` returns
+  the set of files, the :class:`FileInput` object's new :meth:`~fileinput.fileno` returns
   the file descriptor for the currently opened file. (Contributed by Georg
   Brandl.)