Followup to r83869 and issue #8524: rename socket.forget() to socket.detach()

and make it return the file descriptor.

Doc/library/socket.rst

@@ -538,6 +538,15 @@ correspond to Unix system calls applicable to sockets.
    connects.
 
 
+.. method:: socket.detach()
+
+   Put the socket object into closed state without actually closing the
+   underlying file descriptor.  The file descriptor is returned, and can
+   be reused for other purposes.
+
+   .. versionadded:: 3.2
+
+
 .. method:: socket.fileno()
 
    Return the socket's file descriptor (a small integer).  This is useful with
@@ -548,14 +557,6 @@ correspond to Unix system calls applicable to sockets.
    this limitation.
 
 
-.. method:: socket.forget()
-
-   Put the socket object into closed state without actually closing the
-   underlying file descriptor.  This allows the latter to be reused.
-
-   .. versionadded:: 3.2
-
-
 .. method:: socket.getpeername()
 
    Return the remote address to which the socket is connected.  This is useful to

Doc/whatsnew/3.2.rst

@@ -136,7 +136,7 @@ New, Improved, and Deprecated Modules
 
   (Contributed by Tarek Ziadé.)
 
-* Socket objects now have a :meth:`~socket.socket.forget()` method which
+* Socket objects now have a :meth:`~socket.socket.detach()` method which
   puts the socket into closed state without actually closing the underlying
   file descriptor.  The latter can then be reused for other purposes.
 

Lib/ssl.py

@@ -157,7 +157,7 @@ class SSLSocket(socket):
                     raise
             else:
                 connected = True
-            sock.forget()
+            sock.detach()
         elif fileno is not None:
             socket.__init__(self, fileno=fileno)
         else:

Lib/test/test_socket.py

@@ -655,17 +655,21 @@ class BasicTCPTest(SocketConnectedTest):
         self.serv_conn.send(MSG)
         self.serv_conn.shutdown(2)
 
-    def testForget(self):
-        # Testing forget()
-        f = self.cli_conn.fileno()
-        self.cli_conn.forget()
+    def testDetach(self):
+        # Testing detach()
+        fileno = self.cli_conn.fileno()
+        f = self.cli_conn.detach()
+        self.assertEqual(f, fileno)
+        # cli_conn cannot be used anymore...
         self.assertRaises(socket.error, self.cli_conn.recv, 1024)
         self.cli_conn.close()
+        # ...but we can create another socket using the (still open)
+        # file descriptor
         sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, fileno=f)
         msg = sock.recv(1024)
         self.assertEqual(msg, MSG)
 
-    def _testForget(self):
+    def _testDetach(self):
         self.serv_conn.send(MSG)
 
 @unittest.skipUnless(thread, 'Threading required for this test.')

Misc/NEWS

@@ -30,7 +30,7 @@ Core and Builtins
 Extensions
 ----------
 
-- Issue #8524: Add a forget() method to socket objects, so as to put the
+- Issue #8524: Add a detach() method to socket objects, so as to put the
   socket into the closed state without closing the underlying file
   descriptor.
 

Modules/socketmodule.c

@@ -1870,19 +1870,19 @@ PyDoc_STRVAR(close_doc,
 Close the socket.  It cannot be used after this call.");
 
 static PyObject *
-sock_forget(PySocketSockObject *s)
+sock_detach(PySocketSockObject *s)
 {
+    SOCKET_T fd = s->sock_fd;
     s->sock_fd = -1;
-    Py_INCREF(Py_None);
-    return Py_None;
+    return PyLong_FromSocket_t(fd);
 }
 
-PyDoc_STRVAR(forget_doc,
-"forget()\n\
+PyDoc_STRVAR(detach_doc,
+"detach()\n\
 \n\
 Close the socket object without closing the underlying file descriptor.\
 The object cannot be used after this call, but the file descriptor\
-can be reused for other purposes.");
+can be reused for other purposes.  The file descriptor is returned.");
 
 static int
 internal_connect(PySocketSockObject *s, struct sockaddr *addr, int addrlen,
@@ -2772,10 +2772,10 @@ static PyMethodDef sock_methods[] = {
                       connect_doc},
     {"connect_ex",        (PyCFunction)sock_connect_ex, METH_O,
                       connect_ex_doc},
+    {"detach",            (PyCFunction)sock_detach, METH_NOARGS,
+                      detach_doc},
     {"fileno",            (PyCFunction)sock_fileno, METH_NOARGS,
                       fileno_doc},
-    {"forget",            (PyCFunction)sock_forget, METH_NOARGS,
-                      forget_doc},
 #ifdef HAVE_GETPEERNAME
     {"getpeername",       (PyCFunction)sock_getpeername,
                       METH_NOARGS, getpeername_doc},