bpo-44011: Document ssl_shutdown_timeout added by revisited asyncio SSL implementation (GH-31597)

1 files changed, 55 insertions, 5 deletions

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 0c65d75..1b762a7 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -369,6 +369,7 @@ Opening network connections
                           family=0, proto=0, flags=0, sock=None, \
                           local_addr=None, server_hostname=None, \
                           ssl_handshake_timeout=None, \
+                          ssl_shutdown_timeout=None, \
                           happy_eyeballs_delay=None, interleave=None)
 
    Open a streaming transport connection to a given
@@ -456,6 +457,10 @@ Opening network connections
      to wait for the TLS handshake to complete before aborting the connection.
      ``60.0`` seconds if ``None`` (default).
 
+   * *ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown
+     to complete before aborting the connection. ``30.0`` seconds if ``None``
+     (default).
+
    .. versionchanged:: 3.5
 
       Added support for SSL/TLS in :class:`ProactorEventLoop`.
@@ -484,6 +489,10 @@ Opening network connections
 
       For more information: https://tools.ietf.org/html/rfc6555
 
+   .. versionchanged:: 3.11
+
+      Added the *ssl_shutdown_timeout* parameter.
+
    .. seealso::
 
       The :func:`open_connection` function is a high-level alternative
@@ -569,7 +578,8 @@ Opening network connections
 
 .. coroutinemethod:: loop.create_unix_connection(protocol_factory, \
                         path=None, *, ssl=None, sock=None, \
-                        server_hostname=None, ssl_handshake_timeout=None)
+                        server_hostname=None, ssl_handshake_timeout=None, \
+                        ssl_shutdown_timeout=None)
 
    Create a Unix connection.
 
@@ -592,6 +602,10 @@ Opening network connections
       Added the *ssl_handshake_timeout* parameter.
       The *path* parameter can now be a :term:`path-like object`.
 
+   .. versionchanged:: 3.11
+
+      Added the *ssl_shutdown_timeout* parameter.
+
 
 Creating network servers
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -602,7 +616,9 @@ Creating network servers
                         flags=socket.AI_PASSIVE, \
                         sock=None, backlog=100, ssl=None, \
                         reuse_address=None, reuse_port=None, \
-                        ssl_handshake_timeout=None, start_serving=True)
+                        ssl_handshake_timeout=None, \
+                        ssl_shutdown_timeout=None, \
+                        start_serving=True)
 
    Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) listening
    on *port* of the *host* address.
@@ -662,6 +678,10 @@ Creating network servers
      for the TLS handshake to complete before aborting the connection.
      ``60.0`` seconds if ``None`` (default).
 
+   * *ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown
+     to complete before aborting the connection. ``30.0`` seconds if ``None``
+     (default).
+
    * *start_serving* set to ``True`` (the default) causes the created server
      to start accepting connections immediately.  When set to ``False``,
      the user should await on :meth:`Server.start_serving` or
@@ -682,6 +702,10 @@ Creating network servers
       The socket option :py:data:`~socket.TCP_NODELAY` is set by default
       for all TCP connections.
 
+   .. versionchanged:: 3.11
+
+      Added the *ssl_shutdown_timeout* parameter.
+
    .. seealso::
 
       The :func:`start_server` function is a higher-level alternative API
@@ -691,7 +715,9 @@ Creating network servers
 
 .. coroutinemethod:: loop.create_unix_server(protocol_factory, path=None, \
                           *, sock=None, backlog=100, ssl=None, \
-                          ssl_handshake_timeout=None, start_serving=True)
+                          ssl_handshake_timeout=None, \
+                          ssl_shutdown_timeout=None, \
+                          start_serving=True)
 
    Similar to :meth:`loop.create_server` but works with the
    :py:data:`~socket.AF_UNIX` socket family.
@@ -711,8 +737,14 @@ Creating network servers
       Added the *ssl_handshake_timeout* and *start_serving* parameters.
       The *path* parameter can now be a :class:`~pathlib.Path` object.
 
+   .. versionchanged:: 3.11
+
+      Added the *ssl_shutdown_timeout* parameter.
+
+
 .. coroutinemethod:: loop.connect_accepted_socket(protocol_factory, \
-                        sock, *, ssl=None, ssl_handshake_timeout=None)
+                        sock, *, ssl=None, ssl_handshake_timeout=None, \
+                        ssl_shutdown_timeout=None)
 
    Wrap an already accepted connection into a transport/protocol pair.
 
@@ -734,6 +766,10 @@ Creating network servers
      wait for the SSL handshake to complete before aborting the connection.
      ``60.0`` seconds if ``None`` (default).
 
+   * *ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown
+     to complete before aborting the connection. ``30.0`` seconds if ``None``
+     (default).
+
    Returns a ``(transport, protocol)`` pair.
 
    .. versionadded:: 3.5.3
@@ -742,6 +778,10 @@ Creating network servers
 
       Added the *ssl_handshake_timeout* parameter.
 
+   .. versionchanged:: 3.11
+
+      Added the *ssl_shutdown_timeout* parameter.
+
 
 Transferring files
 ^^^^^^^^^^^^^^^^^^
@@ -778,7 +818,8 @@ TLS Upgrade
 
 .. coroutinemethod:: loop.start_tls(transport, protocol, \
                         sslcontext, *, server_side=False, \
-                        server_hostname=None, ssl_handshake_timeout=None)
+                        server_hostname=None, ssl_handshake_timeout=None, \
+                        ssl_shutdown_timeout=None)
 
    Upgrade an existing transport-based connection to TLS.
 
@@ -804,8 +845,17 @@ TLS Upgrade
      wait for the TLS handshake to complete before aborting the connection.
      ``60.0`` seconds if ``None`` (default).
 
+   * *ssl_shutdown_timeout* is the time in seconds to wait for the SSL shutdown
+     to complete before aborting the connection. ``30.0`` seconds if ``None``
+     (default).
+
    .. versionadded:: 3.7
 
+   .. versionchanged:: 3.11
+
+      Added the *ssl_shutdown_timeout* parameter.
+
+
 
 Watching file descriptors
 ^^^^^^^^^^^^^^^^^^^^^^^^^