Issue #17401: document closefd in io.FileIO docs and add to repr

closefd was documented in the open docs but not the matching FileIO
class documented. Further, closefd, part of the core state for the
object was not shown.

In review it was noted that the open docs are a little confusing about
the interaction between closefd and paths, so tweaked them at the same
time.

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index b4433bfd532c0f6a1fd00abce85975ab7f07c8ca..60fadcaa4bc7193351b045a9d1714293e65095b5 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -995,8 +995,8 @@ are always available.  They are listed here in alphabetical order.
 
    If *closefd* is ``False`` and a file descriptor rather than a filename was
    given, the underlying file descriptor will be kept open when the file is
-   closed.  If a filename is given *closefd* has no effect and must be ``True``
-   (the default).
+   closed.  If a filename is given *closefd* must be ``True`` (the default)
+   otherwise an error will be raised.
 
    A custom opener can be used by passing a callable as *opener*. The underlying
    file descriptor for the file object is then obtained by calling *opener* with

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 533ba9d73b63b5c7e35a983e700f8237abd94f03..005428659d35c7232d0bb13ca0367bab6b2da58c 100644 (file)
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -519,9 +519,12 @@ Raw File I/O
    The *name* can be one of two things:
 
    * a character string or :class:`bytes` object representing the path to the
-     file which will be opened;
+     file which will be opened. In this case closefd must be True (the default)
+     otherwise an error will be raised.
    * an integer representing the number of an existing OS-level file descriptor
-     to which the resulting :class:`FileIO` object will give access.
+     to which the resulting :class:`FileIO` object will give access. When the
+     FileIO object is closed this fd will be closed as well, unless *closefd*
+     is set to ``False``.
 
    The *mode* can be ``'r'``, ``'w'``, ``'x'`` or ``'a'`` for reading
    (default), writing, exclusive creation or appending. The file will be

diff --git a/Lib/test/test_fileio.py b/Lib/test/test_fileio.py
index 41be95e04f98faf84628a632e81fd9d9e3a3cf97..7c1a5cebea152f918bac6ffc4ab04e060775e4bc 100644 (file)
--- a/Lib/test/test_fileio.py
+++ b/Lib/test/test_fileio.py
@@ -112,11 +112,13 @@ class AutoFileTests(unittest.TestCase):
         self.assertRaises(TypeError, self.f.write, "Hello!")
 
     def testRepr(self):
-        self.assertEqual(repr(self.f), "<_io.FileIO name=%r mode=%r>"
-                                        % (self.f.name, self.f.mode))
+        self.assertEqual(
+            repr(self.f), "<_io.FileIO name=%r mode=%r closefd='%d'>"
+                          % (self.f.name, self.f.mode, self.f.closefd))
         del self.f.name
-        self.assertEqual(repr(self.f), "<_io.FileIO fd=%r mode=%r>"
-                                        % (self.f.fileno(), self.f.mode))
+        self.assertEqual(
+            repr(self.f), "<_io.FileIO fd=%r mode=%r closefd='%d'>"
+                          % (self.f.fileno(), self.f.mode, self.f.closefd))
         self.f.close()
         self.assertEqual(repr(self.f), "<_io.FileIO [closed]>")
 

diff --git a/Misc/NEWS b/Misc/NEWS
index f1045cae1e1f56f6211bc0fa4a936a2dd9134e7d..5d1b807b76153617ee2ec1daa94306c4412b7611 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -196,6 +196,8 @@ Library
 - Issue #22641: In asyncio, the default SSL context for client connections
   is now created using ssl.create_default_context(), for stronger security.
 
+- Issue #17401: Include closefd in io.FileIO repr.
+
 - Issue #21338: Add silent mode for compileall. quiet parameters of
   compile_{dir, file, path} functions now have a multilevel value. Also,
   -q option of the CLI now have a multilevel value. Patch by Thomas Kluyver.

diff --git a/Modules/_io/fileio.c b/Modules/_io/fileio.c
index 2e0fbf95356605bfd02657fc040896ac3e348a6e..5c1316e9f49f80f38390c3ca3bb77800db490a99 100644 (file)
--- a/Modules/_io/fileio.c
+++ b/Modules/_io/fileio.c
@@ -1054,12 +1054,14 @@ fileio_repr(fileio *self)
             PyErr_Clear();
         else
             return NULL;
-        res = PyUnicode_FromFormat("<_io.FileIO fd=%d mode='%s'>",
-                                   self->fd, mode_string(self));
+        res = PyUnicode_FromFormat(
+           "<_io.FileIO fd=%d mode='%s' closefd='%d'>",
+           self->fd, mode_string(self), self->closefd);
     }
     else {
-        res = PyUnicode_FromFormat("<_io.FileIO name=%R mode='%s'>",
-                                   nameobj, mode_string(self));
+        res = PyUnicode_FromFormat(
+           "<_io.FileIO name=%R mode='%s' closefd='%d'>",
+           nameobj, mode_string(self), self->closefd);
         Py_DECREF(nameobj);
     }
     return res;