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

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

diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index ec4aeaa04395ac1408efcfb0d2058cef0f8ab20d..6a95a4a6e8d18321bdb043f8d32e7436b0cfb19d 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 69afadff1f5f425eaad72b4f0272621c1133ad62..4ca7a64451d4c729111e65912a1c09ceb3258361 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 773fca45c8e70aca8a838721a4561bdbde0508ad..01a24172e5d3dcead973ef4c10c18fe953ad7776 100644 (file)
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -2571,7 +2571,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 c3cf48316b3248bc4633360e7c1e058f9d98b19c..14f11b40cb9b004925aed15699c03f7902627557 100644 (file)
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -858,7 +858,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 42314648fec2bd8c078ee86ec566279a7504789e..b2baa54d9522df65bd83791c26377bba2e845706 100644 (file)
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -147,7 +147,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 caf8804db440a42410e0f648237535734ac1c0e3..4f12fd0f0459b933a752451a77a21f9003e1efc6 100644 (file)
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -43,7 +43,6 @@ Doc/library/asyncio-task.rst
 Doc/library/audioop.rst
 Doc/library/bdb.rst
 Doc/library/bisect.rst
-Doc/library/bz2.rst
 Doc/library/calendar.rst
 Doc/library/cgi.rst
 Doc/library/chunk.rst
@@ -112,7 +111,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.)