[Python-checkins] cpython (3.4): asyncio doc: reformat create_server() doc

[victor.stinner]

https://hg.python.org/cpython/rev/353431a21237
changeset:   93011:353431a21237
branch:      3.4
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Sun Oct 12 20:36:04 2014 +0200
summary:
  asyncio doc: reformat create_server() doc

Fix also the reate_unix_connection() doc: the method is not support on Windows,
not need to mention that ssl is not support with ProactorEventLoop.

files:
  Doc/library/asyncio-eventloop.rst  |  64 +++++++++--------
  Doc/library/asyncio-eventloops.rst |   2 +-
  2 files changed, 35 insertions(+), 31 deletions(-)


diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -258,8 +258,6 @@
    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.
@@ -270,36 +268,42 @@
 
 .. 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,
-   its :attr:`~Server.sockets` attribute contains created sockets. Use the
-   :meth:`Server.close` method to stop the server: close listening sockets.
+   Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) 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.
+
+   Parameters:
+
+   * 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
+     :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`).
+
+   * *flags* is a bitmask for :meth:`getaddrinfo`.
+
+   * *sock* can optionally be specified in order to use a preexisting
+     socket object. If specified, *host* and *port* should be omitted (must be
+     :const:`None`).
+
+   * *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
+     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.
 
    This method is a :ref:`coroutine <coroutine>`.
 
-   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
-   :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`).
-
-   *flags* is a bitmask for :meth:`getaddrinfo`.
-
-   *sock* can optionally be specified in order to use a preexisting
-   socket object.
-
-   *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
-   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::
@@ -462,7 +466,7 @@
 
    *protocol_factory* should instantiate object with :class:`BaseProtocol`
    interface. *pipe* is file-like object.
-   Return pair (transport, protocol), where transport support
+   Return pair (transport, protocol), where *transport* supports
    :class:`WriteTransport` interface.
 
    With :class:`SelectorEventLoop` event loop, the *pipe* is set to
diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst
--- a/Doc/library/asyncio-eventloops.rst
+++ b/Doc/library/asyncio-eventloops.rst
@@ -76,7 +76,7 @@
 
 Common limits of Windows event loops:
 
-- :meth:`~BaseEventLoop.create_unix_server` and
+- :meth:`~BaseEventLoop.create_unix_connection` and
   :meth:`~BaseEventLoop.create_unix_server` are not supported: the socket
   family :data:`socket.AF_UNIX` is specific to UNIX
 - :meth:`~BaseEventLoop.add_signal_handler` and

-- 
Repository URL: https://hg.python.org/cpython