https://github.com/python/cpython/commit/886a4d74ee7b19d027fae1ba4579a99a805878a2
commit: 886a4d74ee7b19d027fae1ba4579a99a805878a2
branch: main
author: Cody Maloney <[email protected]>
committer: hauntsaninja <[email protected]>
date: 2025-03-06T17:18:22-08:00
summary:
gh-129011: Update comments in FileIO to match current code (#129012)
files:
M Lib/_pyio.py
M Modules/_io/clinic/fileio.c.h
M Modules/_io/fileio.c
diff --git a/Lib/_pyio.py b/Lib/_pyio.py
index e915e5b138a623..99d6f796de416e 100644
--- a/Lib/_pyio.py
+++ b/Lib/_pyio.py
@@ -1645,7 +1645,13 @@ def _checkWritable(self, msg=None):
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 @@ def read(self, size=None):
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 22d27bce67799e..bc816ea030fc80 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 89f1cfe6b20935..54e5270f8161d6 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;
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
