[3.13] gh-101100: Fix sphinx reference warnings around I/O (GH-139592) (#145795)

Co-authored-by: Cody Maloney <cmaloney@users.noreply.github.com>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index 6a70714dc3ee42b456f057c4df2843e819965df3..703feaf7e04ff492e1c383899ad2902a8c94249f 100644 (file)
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -155,7 +155,7 @@ message body, instead setting the payload to the raw body.
 
       Read all the data from the binary file-like object *fp*, parse the
       resulting bytes, and return the message object.  *fp* must support
-      both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
+      both the :meth:`~io.IOBase.readline` and the :meth:`~io.BufferedIOBase.read`
       methods.
 
       The bytes contained in *fp* must be formatted as a block of :rfc:`5322`

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 395cf8ee2ad39c83392d25c4aaa3f949e966b8e0..1e4cdffd3589d3efa08ba93121d48c0654530a03 100644 (file)
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -221,7 +221,7 @@ The following exceptions are the exceptions that are usually raised.
 .. exception:: EOFError
 
    Raised when the :func:`input` function hits an end-of-file condition (EOF)
-   without reading any data. (Note: the :meth:`!io.IOBase.read` and
+   without reading any data. (Note: the :meth:`io.TextIOBase.read` and
    :meth:`io.IOBase.readline` methods return an empty string when they hit EOF.)
 
 

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index f6747d50ef928f25b83008bf71a8d3153f345b83..1ffbae43431f4ed3dab24a8f9f37acf83e5924ad 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1271,8 +1271,8 @@ as internal buffering of data.
 
       This function is intended for low-level I/O.  For normal usage, use the
       built-in function :func:`open`, which returns a :term:`file object` with
-      :meth:`~file.read` and :meth:`~file.write` methods (and many more).  To
-      wrap a file descriptor in a file object, use :func:`fdopen`.
+      :meth:`~io.BufferedIOBase.read` and :meth:`~io.BufferedIOBase.write` methods.
+      To wrap a file descriptor in a file object, use :func:`fdopen`.
 
    .. versionchanged:: 3.3
       Added the *dir_fd* parameter.
@@ -1626,7 +1626,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
       descriptor as returned by :func:`os.open` or :func:`pipe`.  To read a
       "file object" returned by the built-in function :func:`open` or by
       :func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its
-      :meth:`~file.read` or :meth:`~file.readline` methods.
+      :meth:`~io.TextIOBase.read` or :meth:`~io.IOBase.readline` methods.
 
    .. versionchanged:: 3.5
       If the system call is interrupted and the signal handler does not raise an
@@ -1815,7 +1815,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
       descriptor as returned by :func:`os.open` or :func:`pipe`.  To write a "file
       object" returned by the built-in function :func:`open` or by :func:`popen` or
       :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
-      :meth:`~file.write` method.
+      :meth:`~io.TextIOBase.write` method.
 
    .. versionchanged:: 3.5
       If the system call is interrupted and the signal handler does not raise an
@@ -4253,7 +4253,7 @@ to be ignored.
    The current process is replaced immediately. Open file objects and
    descriptors are not flushed, so if there may be data buffered
    on these open files, you should flush them using
-   :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
+   :func:`~io.IOBase.flush` or :func:`os.fsync` before calling an
    :func:`exec\* <execl>` function.
 
    The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in how

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index ac3ce92bde3299af08334178bd45c74f10f8aed7..ed3337db21d5930576b7a1e76a126670da79bd8a 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1348,12 +1348,28 @@ also :func:`os.popen`, :func:`os.fdopen`, and the
 :meth:`~socket.socket.makefile` method of socket objects (and perhaps by
 other functions or methods provided by extension modules).
 
+File objects implement common methods, listed below, to simplify usage in
+generic code. They are expected to be :ref:`context-managers`.
+
 The objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are
 initialized to file objects corresponding to the interpreter's standard
 input, output and error streams; they are all open in text mode and
 therefore follow the interface defined by the :class:`io.TextIOBase`
 abstract class.
 
+.. method:: file.read(size=-1, /)
+
+   Retrieve up to *size* data from the file. As a convenience if *size* is
+   unspecified or -1 retrieve all data available.
+
+.. method:: file.write(data, /)
+
+   Store *data* to the file.
+
+.. method:: file.close()
+
+   Flush any buffers and close the underlying file.
+
 
 Internal types
 --------------