From: Victor Stinner Date: Thu, 23 Jan 2014 10:02:09 +0000 (+0100) Subject: asyncio doc: link create_connection() to open_connection() and create_server() X-Git-Tag: v3.4.0b3~53 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c8ea81330c5d2e8385a7fa45d83c9cccb5ba28f1;p=python 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. --- diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 56ede5ccc7..6fc0c4c77e 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -213,6 +213,11 @@ Creating connections 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 @@ Creating listening connections This method returns a :ref:`coroutine object `. + .. 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 index 6a637534f9..aee0114d23 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -231,6 +231,59 @@ BaseSubprocessTransport 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 `. + +.. 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 `; 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 `. + + StreamReader ------------ @@ -572,59 +625,6 @@ Server 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 `. - -.. 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 `; 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 `. - - Protocol example: TCP echo server and client ============================================