From 41ddcd3f40f8171a396e57b841a74fcc83884eab Mon Sep 17 00:00:00 2001 From: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com> Date: Sat, 26 Feb 2022 18:36:43 +0530 Subject: [PATCH] bpo-44011: Document ssl_shutdown_timeout added by revisited asyncio SSL implementation (GH-31597) --- Doc/library/asyncio-eventloop.rst | 60 ++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 5 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 0c65d75dbf8..1b762a75aed 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 ^^^^^^^^^^^^^^^^^^^^^^^^^