From bf50f10a6dc1f82de10ce4105e30300d7028fa7e Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Wed, 5 Oct 2022 16:54:21 -0700
Subject: [PATCH] GH-88968: Add notes about socket ownership transfers
 (GH-97936)

(cherry picked from commit 74ea204634f8eb4745afd5cb75c3fe7749cf38b5)

Co-authored-by: Guido van Rossum <guido@python.org>
---
 Doc/library/asyncio-eventloop.rst | 24 ++++++++++++++++++++++++
 Doc/library/asyncio-stream.rst    | 24 ++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index c1dddbf64aa6ea..de2ecdcc141dc3 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -456,6 +456,12 @@ Opening network connections
      *happy_eyeballs_delay*, *interleave*
      and *local_addr* should be specified.
 
+     .. note::
+
+        The *sock* argument transfers ownership of the socket to the
+        transport created. To close the socket, call the transport's
+        :meth:`~asyncio.BaseTransport.close` method.
+
    * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
      to bind the socket locally.  The *local_host* and *local_port*
      are looked up using ``getaddrinfo()``, similarly to *host* and *port*.
@@ -554,6 +560,12 @@ Opening network connections
      transport. If specified, *local_addr* and *remote_addr* should be omitted
      (must be :const:`None`).
 
+     .. note::
+
+        The *sock* argument transfers ownership of the socket to the
+        transport created. To close the socket, call the transport's
+        :meth:`~asyncio.BaseTransport.close` method.
+
    See :ref:`UDP echo client protocol <asyncio-udp-echo-client-protocol>` and
    :ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
 
@@ -665,6 +677,12 @@ Creating network servers
    * *sock* can optionally be specified in order to use a preexisting
      socket object. If specified, *host* and *port* must not be specified.
 
+     .. note::
+
+        The *sock* argument transfers ownership of the socket to the
+        server created. To close the socket, call the server's
+        :meth:`~asyncio.Server.close` method.
+
    * *backlog* is the maximum number of queued connections passed to
      :meth:`~socket.socket.listen` (defaults to 100).
 
@@ -766,6 +784,12 @@ Creating network servers
    * *sock* is a preexisting socket object returned from
      :meth:`socket.accept <socket.socket.accept>`.
 
+     .. note::
+
+        The *sock* argument transfers ownership of the socket to the
+        transport created. To close the socket, call the transport's
+        :meth:`~asyncio.BaseTransport.close` method.
+
    * *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over
      the accepted connections.
 
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 9b468670a2521e..ce88d70d6607d9 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -67,6 +67,12 @@ and work with streams:
    The rest of the arguments are passed directly to
    :meth:`loop.create_connection`.
 
+   .. note::
+
+      The *sock* argument transfers ownership of the socket to the
+      :class:`StreamWriter` created. To close the socket, call its
+      :meth:`~asyncio.StreamWriter.close` method.
+
    .. versionchanged:: 3.7
       Added the *ssl_handshake_timeout* parameter.
 
@@ -103,6 +109,12 @@ and work with streams:
    The rest of the arguments are passed directly to
    :meth:`loop.create_server`.
 
+   .. note::
+
+      The *sock* argument transfers ownership of the socket to the
+      server created. To close the socket, call the server's
+      :meth:`~asyncio.Server.close` method.
+
    .. versionchanged:: 3.7
       Added the *ssl_handshake_timeout* and *start_serving* parameters.
 
@@ -123,6 +135,12 @@ and work with streams:
 
    See also the documentation of :meth:`loop.create_unix_connection`.
 
+   .. note::
+
+      The *sock* argument transfers ownership of the socket to the
+      :class:`StreamWriter` created. To close the socket, call its
+      :meth:`~asyncio.StreamWriter.close` method.
+
    .. availability:: Unix.
 
    .. versionchanged:: 3.7
@@ -143,6 +161,12 @@ and work with streams:
 
    See also the documentation of :meth:`loop.create_unix_server`.
 
+   .. note::
+
+      The *sock* argument transfers ownership of the socket to the
+      server created. To close the socket, call the server's
+      :meth:`~asyncio.Server.close` method.
+
    .. availability:: Unix.
 
    .. versionchanged:: 3.7