Closes #22275: asyncio: enhance documentation of OS support

Author: vstinner

Doc/library/asyncio-eventloop.rst

@@ -221,6 +221,8 @@ Creating connections
      to bind the socket to locally.  The *local_host* and *local_port*
      are looked up using getaddrinfo(), similarly to *host* and *port*.
 
+   On Windows with :class:`ProactorEventLoop`, SSL/TLS is not supported.
+
    .. seealso::
 
       The :func:`open_connection` function can be used to get a pair of
@@ -239,6 +241,8 @@ Creating connections
 
    See the :meth:`BaseEventLoop.create_connection` method for parameters.
 
+   On Windows with :class:`ProactorEventLoop`, this method is not supported.
+
 
 .. method:: BaseEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
 
@@ -251,6 +255,8 @@ Creating connections
    establish the connection in the background.  When successful, the
    coroutine returns a ``(transport, protocol)`` pair.
 
+   On Windows with :class:`ProactorEventLoop`, SSL/TLS is not supported.
+
    See the :meth:`BaseEventLoop.create_connection` method for parameters.
 
    Availability: UNIX.
@@ -261,19 +267,19 @@ Creating listening connections
 
 .. method:: BaseEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None)
 
-   Create a TCP server bound to host and port. Return a :class:`Server` object,
+   Create a TCP server bound to *host* and *port*. Return a :class:`Server` object,
    its :attr:`~Server.sockets` attribute contains created sockets. Use the
    :meth:`Server.close` method to stop the server: close listening sockets.
 
    This method is a :ref:`coroutine <coroutine>`.
 
-   If *host* is an empty string or None all interfaces are assumed
+   If *host* is an empty string or ``None``, all interfaces are assumed
    and a list of multiple sockets will be returned (most likely
    one for IPv4 and another one for IPv6).
 
-   *family* can be set to either :data:`~socket.AF_INET` or
+   *family* can be set to either :data:`socket.AF_INET` or
    :data:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6. If not set
-   it will be determined from host (defaults to :data:`~socket.AF_UNSPEC`).
+   it will be determined from host (defaults to :data:`socket.AF_UNSPEC`).
 
    *flags* is a bitmask for :meth:`getaddrinfo`.
 
@@ -283,14 +289,16 @@ Creating listening connections
    *backlog* is the maximum number of queued connections passed to
    :meth:`~socket.socket.listen` (defaults to 100).
 
-   ssl can be set to an :class:`~ssl.SSLContext` to enable SSL over the
+   *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the
    accepted connections.
 
    *reuse_address* tells the kernel to reuse a local socket in
    TIME_WAIT state, without waiting for its natural timeout to
    expire. If not specified will automatically be set to True on
    UNIX.
 
+   On Windows with :class:`ProactorEventLoop`, SSL/TLS is not supported.
+
    .. seealso::
 
       The function :func:`start_server` creates a (:class:`StreamReader`,
@@ -308,6 +316,11 @@ Creating listening connections
 Watch file descriptors
 ----------------------
 
+On Windows with :class:`SelectorEventLoop`, only socket handles are supported
+(ex: pipe file descriptors are not supported).
+
+On Windows with :class:`ProactorEventLoop`, these methods are not supported.
+
 .. method:: BaseEventLoop.add_reader(fd, callback, \*args)
 
    Start watching the file descriptor for read availability and then call the
@@ -419,6 +432,9 @@ Resolve host name
 Connect pipes
 -------------
 
+On Windows with :class:`SelectorEventLoop`, these methods are not supported.
+Use :class:`ProactorEventLoop` to support pipes on Windows.
+
 .. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
 
    Register read pipe in eventloop.

Doc/library/asyncio-eventloops.rst

@@ -39,6 +39,10 @@ asyncio currently provides two implementations of event loops:
 
    Use the most efficient selector available on the platform.
 
+   On Windows, only sockets are supported (ex: pipes are not supported):
+   see the `MSDN documentation of select
+   <http://msdn.microsoft.com/en-us/library/windows/desktop/ms740141%28v=vs.85%29.aspx>`_.
+
 .. class:: ProactorEventLoop
 
    Proactor event loop for Windows using "I/O Completion Ports" aka IOCP.
@@ -83,9 +87,7 @@ Common limits of Windows event loops:
 
 :class:`SelectorEventLoop` specific limits:
 
-- :class:`~selectors.SelectSelector` is used but it only supports sockets,
-  see the `MSDN documentation of select
-  <http://msdn.microsoft.com/en-us/library/windows/desktop/ms740141%28v=vs.85%29.aspx>`_
+- :class:`~selectors.SelectSelector` is used but it only supports sockets
 - :meth:`~BaseEventLoop.add_reader` and :meth:`~BaseEventLoop.add_writer` only
   accept file descriptors of sockets
 - Pipes are not supported