gh-129011: Update comments in FileIO to match current code (#129012)

3 files changed, 43 insertions, 16 deletions

diff --git a/Lib/_pyio.py b/Lib/_pyio.py
index e915e5b..99d6f79 100644
--- a/Lib/_pyio.py
+++ b/Lib/_pyio.py
@@ -1645,7 +1645,13 @@ class FileIO(RawIOBase):
     def read(self, size=None):
         """Read at most size bytes, returned as bytes.
 
-        Only makes one system call, so less data may be returned than requested
+        If size is less than 0, read all bytes in the file making
+        multiple read calls. See ``FileIO.readall``.
+
+        Attempts to make only one system call, retrying only per
+        PEP 475 (EINTR). This means less data may be returned than
+        requested.
+
         In non-blocking mode, returns None if no data is available.
         Return an empty bytes object at EOF.
         """
@@ -1661,8 +1667,13 @@ class FileIO(RawIOBase):
     def readall(self):
         """Read all data from the file, returned as bytes.
 
-        In non-blocking mode, returns as much as is immediately available,
-        or None if no data is available.  Return an empty bytes object at EOF.
+        Reads until either there is an error or read() returns size 0
+        (indicates EOF). If the file is already at EOF, returns an
+        empty bytes object.
+
+        In non-blocking mode, returns as much data as could be read
+        before EAGAIN. If no data is available (EAGAIN is returned
+        before bytes are read) returns None.
         """
         self._checkClosed()
         self._checkReadable()
diff --git a/Modules/_io/clinic/fileio.c.h b/Modules/_io/clinic/fileio.c.h
index 22d27bc..bc816ea 100644
--- a/Modules/_io/clinic/fileio.c.h
+++ b/Modules/_io/clinic/fileio.c.h
@@ -268,8 +268,11 @@ PyDoc_STRVAR(_io_FileIO_readall__doc__,
 "\n"
 "Read all data from the file, returned as bytes.\n"
 "\n"
-"In non-blocking mode, returns as much as is immediately available,\n"
-"or None if no data is available.  Return an empty bytes object at EOF.");
+"Reads until either there is an error or read() returns size 0 (indicates EOF).\n"
+"If the file is already at EOF, returns an empty bytes object.\n"
+"\n"
+"In non-blocking mode, returns as much data as could be read before EAGAIN. If no\n"
+"data is available (EAGAIN is returned before bytes are read) returns None.");
 
 #define _IO_FILEIO_READALL_METHODDEF    \
     {"readall", (PyCFunction)_io_FileIO_readall, METH_NOARGS, _io_FileIO_readall__doc__},
@@ -289,9 +292,14 @@ PyDoc_STRVAR(_io_FileIO_read__doc__,
 "\n"
 "Read at most size bytes, returned as bytes.\n"
 "\n"
-"Only makes one system call, so less data may be returned than requested.\n"
-"In non-blocking mode, returns None if no data is available.\n"
-"Return an empty bytes object at EOF.");
+"If size is less than 0, read all bytes in the file making multiple read calls.\n"
+"See ``FileIO.readall``.\n"
+"\n"
+"Attempts to make only one system call, retrying only per PEP 475 (EINTR). This\n"
+"means less data may be returned than requested.\n"
+"\n"
+"In non-blocking mode, returns None if no data is available. Return an empty\n"
+"bytes object at EOF.");
 
 #define _IO_FILEIO_READ_METHODDEF    \
     {"read", _PyCFunction_CAST(_io_FileIO_read), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_read__doc__},
@@ -533,4 +541,4 @@ _io_FileIO_isatty(PyObject *self, PyObject *Py_UNUSED(ignored))
 #ifndef _IO_FILEIO_TRUNCATE_METHODDEF
     #define _IO_FILEIO_TRUNCATE_METHODDEF
 #endif /* !defined(_IO_FILEIO_TRUNCATE_METHODDEF) */
-/*[clinic end generated code: output=dcbeb6a0b13e4b1f input=a9049054013a1b77]*/
+/*[clinic end generated code: output=f4e1f74c03d4ecdf input=a9049054013a1b77]*/
diff --git a/Modules/_io/fileio.c b/Modules/_io/fileio.c
index 89f1cfe..54e5270 100644
--- a/Modules/_io/fileio.c
+++ b/Modules/_io/fileio.c
@@ -727,13 +727,16 @@ _io.FileIO.readall
 
 Read all data from the file, returned as bytes.
 
-In non-blocking mode, returns as much as is immediately available,
-or None if no data is available.  Return an empty bytes object at EOF.
+Reads until either there is an error or read() returns size 0 (indicates EOF).
+If the file is already at EOF, returns an empty bytes object.
+
+In non-blocking mode, returns as much data as could be read before EAGAIN. If no
+data is available (EAGAIN is returned before bytes are read) returns None.
 [clinic start generated code]*/
 
 static PyObject *
 _io_FileIO_readall_impl(fileio *self)
-/*[clinic end generated code: output=faa0292b213b4022 input=dbdc137f55602834]*/
+/*[clinic end generated code: output=faa0292b213b4022 input=1e19849857f5d0a1]*/
 {
     Py_off_t pos, end;
     PyObject *result;
@@ -848,14 +851,19 @@ _io.FileIO.read
 
 Read at most size bytes, returned as bytes.
 
-Only makes one system call, so less data may be returned than requested.
-In non-blocking mode, returns None if no data is available.
-Return an empty bytes object at EOF.
+If size is less than 0, read all bytes in the file making multiple read calls.
+See ``FileIO.readall``.
+
+Attempts to make only one system call, retrying only per PEP 475 (EINTR). This
+means less data may be returned than requested.
+
+In non-blocking mode, returns None if no data is available. Return an empty
+bytes object at EOF.
 [clinic start generated code]*/
 
 static PyObject *
 _io_FileIO_read_impl(fileio *self, PyTypeObject *cls, Py_ssize_t size)
-/*[clinic end generated code: output=bbd749c7c224143e input=f613d2057e4a1918]*/
+/*[clinic end generated code: output=bbd749c7c224143e input=cf21fddef7d38ab6]*/
 {
     char *ptr;
     Py_ssize_t n;