asyncio doc: Move streams to their own dedicated page

diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
index aee0114d23de9815e93c4bd61d2608e646929840..15d8db8815ae11a1e5d7b14e7989099852202ae3 100644 (file)
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -1,8 +1,8 @@
 .. currentmodule:: asyncio
 
-+++++++++++++++++++++++++++++++++
-Transports, streams and protocols
-+++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++
+Transports  and protocols
++++++++++++++++++++++++++
 
 .. _transport:
 
@@ -228,212 +228,6 @@ BaseSubprocessTransport
       stop the subprocess.
 
 
-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
-------------
-
-.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
-
-   .. method:: exception()
-
-      Get the exception.
-
-   .. method:: feed_eof()
-
-      XXX
-
-   .. method:: feed_data(data)
-
-      XXX
-
-   .. method:: set_exception(exc)
-
-      Set the exception.
-
-   .. method:: set_transport(transport)
-
-      Set the transport.
-
-   .. method:: read(n=-1)
-
-      XXX
-
-      This method returns a :ref:`coroutine object <coroutine>`.
-
-   .. method:: readline()
-
-      XXX
-
-      This method returns a :ref:`coroutine object <coroutine>`.
-
-   .. method:: readexactly(n)
-
-      XXX
-
-      This method returns a :ref:`coroutine object <coroutine>`.
-
-
-StreamWriter
-------------
-
-.. class:: StreamWriter(transport, protocol, reader, loop)
-
-   Wraps a Transport.
-
-   This exposes :meth:`write`, :meth:`writelines`, :meth:`can_write_eof()`,
-   :meth:`write_eof`, :meth:`get_extra_info` and :meth:`close`.  It adds
-   :meth:`drain` which returns an optional :class:`Future` on which you can
-   wait for flow control.  It also adds a transport attribute which references
-   the :class:`Transport` directly.
-
-   .. attribute:: transport
-
-      Transport.
-
-   .. method:: close()
-
-      Close the transport: see :meth:`BaseTransport.close`.
-
-   .. method:: drain()
-
-      This method has an unusual return value.
-
-      The intended use is to write::
-
-          w.write(data)
-          yield from w.drain()
-
-      When there's nothing to wait for, :meth:`drain()` returns ``()``, and the
-      yield-from continues immediately.  When the transport buffer is full (the
-      protocol is paused), :meth:`drain` creates and returns a
-      :class:`Future` and the yield-from will block until
-      that Future is completed, which will happen when the buffer is
-      (partially) drained and the protocol is resumed.
-
-   .. method:: get_extra_info(name, default=None)
-
-      Return optional transport information: see
-      :meth:`BaseTransport.get_extra_info`.
-
-   .. method:: write(data)
-
-      Write some *data* bytes to the transport: see
-      :meth:`WriteTransport.write`.
-
-   .. method:: writelines(data)
-
-      Write a list (or any iterable) of data bytes to the transport:
-      see :meth:`WriteTransport.writelines`.
-
-   .. method:: can_write_eof()
-
-      Return :const:`True` if the transport supports :meth:`write_eof`,
-      :const:`False` if not. See :meth:`WriteTransport.can_write_eof`.
-
-   .. method:: write_eof()
-
-      Close the write end of the transport after flushing buffered data:
-      see :meth:`WriteTransport.write_eof`.
-
-
-StreamReaderProtocol
---------------------
-
-.. class:: StreamReaderProtocol(stream_reader, client_connected_cb=None, loop=None)
-
-    Trivial helper class to adapt between :class:`Protocol` and
-    :class:`StreamReader`. Sublclass of :class:`Protocol`.
-
-    *stream_reader* is a :class:`StreamReader` instance, *client_connected_cb*
-    is an optional function called with (stream_reader, stream_writer) when a
-    connection is made, *loop* is the event loop instance to use.
-
-    (This is a helper class instead of making :class:`StreamReader` itself a
-    :class:`Protocol` subclass, because the :class:`StreamReader` has other
-    potential uses, and to prevent the user of the :class:`StreamReader` to
-    accidentally call inappropriate methods of the protocol.)
-
-    .. method:: connection_made(transport)
-
-       XXX
-
-    .. method:: connection_lost(exc)
-
-       XXX
-
-    .. method:: data_received(data)
-
-       XXX
-
-    .. method:: eof_received()
-
-       XXX
-
-    .. method:: pause_writing()
-
-       XXX
-
-    .. method:: resume_writing()
-
-       XXX
-
-
-
 .. _protocol:
 
 Protocols

diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
new file mode 100644 (file)
index 0000000..19ac103
--- /dev/null
+++ b/Doc/library/asyncio-stream.rst
@@ -0,0 +1,207 @@
+.. currentmodule:: asyncio
+
++++++++
+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
+============
+
+.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
+
+   .. method:: exception()
+
+      Get the exception.
+
+   .. method:: feed_eof()
+
+      XXX
+
+   .. method:: feed_data(data)
+
+      XXX
+
+   .. method:: set_exception(exc)
+
+      Set the exception.
+
+   .. method:: set_transport(transport)
+
+      Set the transport.
+
+   .. method:: read(n=-1)
+
+      XXX
+
+      This method returns a :ref:`coroutine object <coroutine>`.
+
+   .. method:: readline()
+
+      XXX
+
+      This method returns a :ref:`coroutine object <coroutine>`.
+
+   .. method:: readexactly(n)
+
+      XXX
+
+      This method returns a :ref:`coroutine object <coroutine>`.
+
+
+StreamWriter
+============
+
+.. class:: StreamWriter(transport, protocol, reader, loop)
+
+   Wraps a Transport.
+
+   This exposes :meth:`write`, :meth:`writelines`, :meth:`can_write_eof()`,
+   :meth:`write_eof`, :meth:`get_extra_info` and :meth:`close`.  It adds
+   :meth:`drain` which returns an optional :class:`Future` on which you can
+   wait for flow control.  It also adds a transport attribute which references
+   the :class:`Transport` directly.
+
+   .. attribute:: transport
+
+      Transport.
+
+   .. method:: close()
+
+      Close the transport: see :meth:`BaseTransport.close`.
+
+   .. method:: drain()
+
+      This method has an unusual return value.
+
+      The intended use is to write::
+
+          w.write(data)
+          yield from w.drain()
+
+      When there's nothing to wait for, :meth:`drain()` returns ``()``, and the
+      yield-from continues immediately.  When the transport buffer is full (the
+      protocol is paused), :meth:`drain` creates and returns a
+      :class:`Future` and the yield-from will block until
+      that Future is completed, which will happen when the buffer is
+      (partially) drained and the protocol is resumed.
+
+   .. method:: get_extra_info(name, default=None)
+
+      Return optional transport information: see
+      :meth:`BaseTransport.get_extra_info`.
+
+   .. method:: write(data)
+
+      Write some *data* bytes to the transport: see
+      :meth:`WriteTransport.write`.
+
+   .. method:: writelines(data)
+
+      Write a list (or any iterable) of data bytes to the transport:
+      see :meth:`WriteTransport.writelines`.
+
+   .. method:: can_write_eof()
+
+      Return :const:`True` if the transport supports :meth:`write_eof`,
+      :const:`False` if not. See :meth:`WriteTransport.can_write_eof`.
+
+   .. method:: write_eof()
+
+      Close the write end of the transport after flushing buffered data:
+      see :meth:`WriteTransport.write_eof`.
+
+
+StreamReaderProtocol
+====================
+
+.. class:: StreamReaderProtocol(stream_reader, client_connected_cb=None, loop=None)
+
+    Trivial helper class to adapt between :class:`Protocol` and
+    :class:`StreamReader`. Sublclass of :class:`Protocol`.
+
+    *stream_reader* is a :class:`StreamReader` instance, *client_connected_cb*
+    is an optional function called with (stream_reader, stream_writer) when a
+    connection is made, *loop* is the event loop instance to use.
+
+    (This is a helper class instead of making :class:`StreamReader` itself a
+    :class:`Protocol` subclass, because the :class:`StreamReader` has other
+    potential uses, and to prevent the user of the :class:`StreamReader` to
+    accidentally call inappropriate methods of the protocol.)
+
+    .. method:: connection_made(transport)
+
+       XXX
+
+    .. method:: connection_lost(exc)
+
+       XXX
+
+    .. method:: data_received(data)
+
+       XXX
+
+    .. method:: eof_received()
+
+       XXX
+
+    .. method:: pause_writing()
+
+       XXX
+
+    .. method:: resume_writing()
+
+       XXX
+

diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
index 2e0e0d59407b6178d41abd3caca2b29200a55853..64e751ba3f5f74e88ec4260d01edf8ea29f28b3d 100644 (file)
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -47,6 +47,7 @@ Table of content:
    asyncio-eventloop.rst
    asyncio-task.rst
    asyncio-protocol.rst
+   asyncio-stream.rst
    asyncio-sync.rst
    asyncio-dev.rst