Add comments around stat_atopen and why bufsize is + 1

Author: cmaloney

Lib/_pyio.py

@@ -1655,6 +1655,10 @@ def readall(self):
         if self._stat_atopen is None or self._stat_atopen.st_size <= 0:
             bufsize = DEFAULT_BUFFER_SIZE
         else:
+            # In order to detect end of file, need a read() of at least 1
+            # byte which returns size 0. Oversize the buffer by 1 byte so the
+            # I/O can be completed with two read() calls (one for all data, one
+            # for EOF) without needing to resize the buffer.
             bufsize = self._stat_atopen.st_size + 1
 
             if self._stat_atopen.st_size > 65536:

Modules/_io/fileio.c

@@ -74,6 +74,11 @@ typedef struct {
     signed int seekable : 2; /* -1 means unknown */
     unsigned int closefd : 1;
     char finalizing;
+    /* Stat result which was grabbed at file open, useful for optimizing common
+    File I/O patterns to be more efficient. This is only guidance / an estimate,
+    as it is subject to Time-Of-Check to Time-Of-Use (TOCTOU) issues / bugs.
+    Both the underlying file descriptor and file may be modified outside of the
+    fileio object / Python (ex. gh-90102, GH-121941, gh-109523). */
     struct _Py_stat_struct *stat_atopen;
     PyObject *weakreflist;
     PyObject *dict;