From a55b4391f671124e9544de1033c5a4e501014230 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Mon, 23 Oct 2023 19:37:25 +0300 Subject: [PATCH 1/4] gh-101100: Fix sphinx warnings in `library/asyncio-eventloop.rst` --- Doc/library/asyncio-eventloop.rst | 14 ++++++++------ Doc/library/socket.rst | 8 ++++++++ Doc/tools/.nitignore | 1 - 3 files changed, 16 insertions(+), 7 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index dcdb0827daf8b7..aea2058c881abf 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -509,7 +509,7 @@ Opening network connections .. versionchanged:: 3.6 - The socket option :py:const:`~socket.TCP_NODELAY` is set by default + The socket option :ref:`socket.TCP_NODELAY ` is set by default for all TCP connections. .. versionchanged:: 3.7 @@ -581,7 +581,7 @@ Opening network connections * *reuse_port* tells the kernel to allow this endpoint to be bound to the same port as other existing endpoints are bound to, so long as they all set this flag when being created. This option is not supported on Windows - and some Unixes. If the :py:const:`~socket.SO_REUSEPORT` constant is not + and some Unixes. If the :ref:`socket.SO_REUSEPORT ` constant is not defined then this capability is unsupported. * *allow_broadcast* tells the kernel to allow this endpoint to send @@ -607,7 +607,8 @@ Opening network connections .. versionchanged:: 3.8.1 The *reuse_address* parameter is no longer supported, as using - :py:const:`~sockets.SO_REUSEADDR` poses a significant security concern for + :ref:`socket.SO_REUSEADDR ` + poses a significant security concern for UDP. Explicitly passing ``reuse_address=True`` will raise an exception. When multiple processes with differing UIDs assign sockets to an @@ -616,7 +617,8 @@ Opening network connections For supported platforms, *reuse_port* can be used as a replacement for similar functionality. With *reuse_port*, - :py:const:`~sockets.SO_REUSEPORT` is used instead, which specifically + :ref:`socket.SO_REUSEPORT ` + is used instead, which specifically prevents processes with differing UIDs from assigning sockets to the same socket address. @@ -756,7 +758,7 @@ Creating network servers .. versionchanged:: 3.6 Added *ssl_handshake_timeout* and *start_serving* parameters. - The socket option :py:const:`~socket.TCP_NODELAY` is set by default + The socket option :ref:`socket.TCP_NODELAY ` is set by default for all TCP connections. .. versionchanged:: 3.11 @@ -1888,7 +1890,7 @@ Set signal handlers for SIGINT and SIGTERM (This ``signals`` example only works on Unix.) -Register handlers for signals :py:data:`SIGINT` and :py:data:`SIGTERM` +Register handlers for signals :const:`~signal.SIGINT` and :const:`~signal.SIGTERM` using the :meth:`loop.add_signal_handler` method:: import asyncio diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index c3cf48316b3248..f2e4967a6a48b4 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -352,6 +352,12 @@ Constants defined then this protocol is unsupported. More constants may be available depending on the system. +.. data:: AF_UNSPEC + + The value :const:`AF_UNSPEC` indicates that + :func:`getaddrinfo` should return socket addresses for any + address family (either IPv4 or IPv6, for example) that can + be used with node and service. .. data:: SOCK_STREAM SOCK_DGRAM @@ -380,6 +386,8 @@ Constants .. versionadded:: 3.2 +.. _unix-constants: + .. data:: SO_* SOMAXCONN MSG_* diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 62e63d6d62960c..a7bc79a5ac5314 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -30,7 +30,6 @@ Doc/howto/logging.rst Doc/howto/urllib2.rst Doc/library/abc.rst Doc/library/ast.rst -Doc/library/asyncio-eventloop.rst Doc/library/asyncio-extending.rst Doc/library/asyncio-policy.rst Doc/library/asyncio-stream.rst From 2f8d442cdf5dae68fef8a34559db77db205997df Mon Sep 17 00:00:00 2001 From: Nikita Sobolev Date: Tue, 24 Oct 2023 17:48:33 +0300 Subject: [PATCH 2/4] Update Doc/library/socket.rst Co-authored-by: Hugo van Kemenade --- Doc/library/socket.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index f2e4967a6a48b4..6ee14016a90afe 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -386,7 +386,7 @@ Constants .. versionadded:: 3.2 -.. _unix-constants: +.. _socket-unix-constants: .. data:: SO_* SOMAXCONN From 6caf31cba05d30dfa7fad9452357d728d05c04a4 Mon Sep 17 00:00:00 2001 From: Nikita Sobolev Date: Tue, 24 Oct 2023 17:49:02 +0300 Subject: [PATCH 3/4] Update asyncio-eventloop.rst --- Doc/library/asyncio-eventloop.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index aea2058c881abf..1a2f7ff6ac2dd0 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -509,7 +509,7 @@ Opening network connections .. versionchanged:: 3.6 - The socket option :ref:`socket.TCP_NODELAY ` is set by default + The socket option :ref:`socket.TCP_NODELAY ` is set by default for all TCP connections. .. versionchanged:: 3.7 @@ -581,7 +581,7 @@ Opening network connections * *reuse_port* tells the kernel to allow this endpoint to be bound to the same port as other existing endpoints are bound to, so long as they all set this flag when being created. This option is not supported on Windows - and some Unixes. If the :ref:`socket.SO_REUSEPORT ` constant is not + and some Unixes. If the :ref:`socket.SO_REUSEPORT ` constant is not defined then this capability is unsupported. * *allow_broadcast* tells the kernel to allow this endpoint to send @@ -607,7 +607,7 @@ Opening network connections .. versionchanged:: 3.8.1 The *reuse_address* parameter is no longer supported, as using - :ref:`socket.SO_REUSEADDR ` + :ref:`socket.SO_REUSEADDR ` poses a significant security concern for UDP. Explicitly passing ``reuse_address=True`` will raise an exception. @@ -617,7 +617,7 @@ Opening network connections For supported platforms, *reuse_port* can be used as a replacement for similar functionality. With *reuse_port*, - :ref:`socket.SO_REUSEPORT ` + :ref:`socket.SO_REUSEPORT ` is used instead, which specifically prevents processes with differing UIDs from assigning sockets to the same socket address. @@ -758,7 +758,7 @@ Creating network servers .. versionchanged:: 3.6 Added *ssl_handshake_timeout* and *start_serving* parameters. - The socket option :ref:`socket.TCP_NODELAY ` is set by default + The socket option :ref:`socket.TCP_NODELAY ` is set by default for all TCP connections. .. versionchanged:: 3.11 From add1ed6209f53a106e166f8b955450394ed94e38 Mon Sep 17 00:00:00 2001 From: Nikita Sobolev Date: Tue, 24 Oct 2023 17:52:21 +0300 Subject: [PATCH 4/4] Update socket.rst --- Doc/library/socket.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 6ee14016a90afe..dfc59f7aade790 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -354,10 +354,9 @@ Constants .. data:: AF_UNSPEC - The value :const:`AF_UNSPEC` indicates that + :const:`AF_UNSPEC` means that :func:`getaddrinfo` should return socket addresses for any - address family (either IPv4 or IPv6, for example) that can - be used with node and service. + address family (either IPv4, IPv6, or any other) that can be used. .. data:: SOCK_STREAM SOCK_DGRAM