[Python-checkins] cpython: asyncio doc: link create_connection() to open_connection() and create_server()

[victor.stinner]

http://hg.python.org/cpython/rev/ccc91994da20
changeset:   88650:ccc91994da20
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Thu Jan 23 11:02:09 2014 +0100
summary:
  asyncio doc: link create_connection() to open_connection() and create_server()
to start_server()

Rename also the "Network functions" section to "Stream functions" and move it to the Stream section.

files:
  Doc/library/asyncio-eventloop.rst |   10 +
  Doc/library/asyncio-protocol.rst  |  106 +++++++++---------
  2 files changed, 63 insertions(+), 53 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
@@ -213,6 +213,11 @@
      to bind the socket to locally.  The *local_host* and *local_port*
      are looked up using getaddrinfo(), similarly to *host* and *port*.
 
+   .. seealso::
+
+      The :func:`open_connection` function can be used to get a pair of
+      (:class:`StreamReader`, :class:`StreamWriter`) instead of a protocol.
+
 
 Creating listening connections
 ------------------------------
@@ -251,6 +256,11 @@
 
    This method returns a :ref:`coroutine object <coroutine>`.
 
+   .. seealso::
+
+      The function :func:`start_server` creates a (:class:`StreamReader`,
+      :class:`StreamWriter`) pair and calls back a function with this pair.
+
 .. method:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0)
 
    Create datagram connection.
diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -231,6 +231,59 @@
 Streams
 =======
 
+Stream functions
+----------------
+
+.. function:: open_connection(host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+
+   A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader,
+   writer) pair.
+
+   The reader returned is a :class:`StreamReader` instance; the writer is
+   a :class:`StreamWriter` instance.
+
+   The arguments are all the usual arguments to
+   :meth:`BaseEventLoop.create_connection` except *protocol_factory*; most
+   common are positional host and port, with various optional keyword arguments
+   following.
+
+   Additional optional keyword arguments are *loop* (to set the event loop
+   instance to use) and *limit* (to set the buffer limit passed to the
+   :class:`StreamReader`).
+
+   (If you want to customize the :class:`StreamReader` and/or
+   :class:`StreamReaderProtocol` classes, just copy the code -- there's really
+   nothing special here except some convenience.)
+
+   This function returns a :ref:`coroutine object <coroutine>`.
+
+.. function:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+
+   Start a socket server, call back for each client connected.
+
+   The first parameter, *client_connected_cb*, takes two parameters:
+   *client_reader*, *client_writer*.  *client_reader* is a
+   :class:`StreamReader` object, while *client_writer* is a
+   :class:`StreamWriter` object.  This parameter can either be a plain callback
+   function or a :ref:`coroutine function <coroutine>`; if it is a coroutine
+   function, it will be automatically converted into a :class:`Task`.
+
+   The rest of the arguments are all the usual arguments to
+   :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
+   common are positional host and port, with various optional keyword arguments
+   following.  The return value is the same as
+   :meth:`~BaseEventLoop.create_server()`.
+
+   Additional optional keyword arguments are *loop* (to set the event loop
+   instance to use) and *limit* (to set the buffer limit passed to the
+   :class:`StreamReader`).
+
+   The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e.
+   a :class:`AbstractServer` object which can be used to stop the service.
+
+   This function returns a :ref:`coroutine object <coroutine>`.
+
+
 StreamReader
 ------------
 
@@ -572,59 +625,6 @@
       Coroutine to wait until service is closed.
 
 
-Network functions
-=================
-
-.. function:: open_connection(host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
-
-   A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader,
-   writer) pair.
-
-   The reader returned is a :class:`StreamReader` instance; the writer is
-   a :class:`StreamWriter` instance.
-
-   The arguments are all the usual arguments to
-   :meth:`BaseEventLoop.create_connection` except *protocol_factory*; most
-   common are positional host and port, with various optional keyword arguments
-   following.
-
-   Additional optional keyword arguments are *loop* (to set the event loop
-   instance to use) and *limit* (to set the buffer limit passed to the
-   :class:`StreamReader`).
-
-   (If you want to customize the :class:`StreamReader` and/or
-   :class:`StreamReaderProtocol` classes, just copy the code -- there's really
-   nothing special here except some convenience.)
-
-   This function returns a :ref:`coroutine object <coroutine>`.
-
-.. function:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
-
-   Start a socket server, call back for each client connected.
-
-   The first parameter, *client_connected_cb*, takes two parameters:
-   *client_reader*, *client_writer*.  *client_reader* is a
-   :class:`StreamReader` object, while *client_writer* is a
-   :class:`StreamWriter` object.  This parameter can either be a plain callback
-   function or a :ref:`coroutine function <coroutine>`; if it is a coroutine
-   function, it will be automatically converted into a :class:`Task`.
-
-   The rest of the arguments are all the usual arguments to
-   :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
-   common are positional host and port, with various optional keyword arguments
-   following.  The return value is the same as
-   :meth:`~BaseEventLoop.create_server()`.
-
-   Additional optional keyword arguments are *loop* (to set the event loop
-   instance to use) and *limit* (to set the buffer limit passed to the
-   :class:`StreamReader`).
-
-   The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e.
-   a :class:`AbstractServer` object which can be used to stop the service.
-
-   This function returns a :ref:`coroutine object <coroutine>`.
-
-
 Protocol example: TCP echo server and client
 ============================================
 

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