asyncio doc: move stream classes to their own class

1 files changed, 74 insertions, 29 deletions

diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
index 2ab168f..6a63753 100644
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -1,8 +1,8 @@
 .. currentmodule:: asyncio
 
-++++++++++++++++++++++++
-Transports and protocols
-++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++
+Transports, streams and protocols
++++++++++++++++++++++++++++++++++
 
 .. _transport:
 
@@ -228,6 +228,53 @@ BaseSubprocessTransport
       stop the subprocess.
 
 
+Streams
+=======
+
+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
 ------------
 
@@ -291,48 +338,46 @@ StreamWriter
       see :meth:`WriteTransport.write_eof`.
 
 
-StreamReader
-------------
-
-.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
-
-   .. method:: exception()
-
-      Get the exception.
-
-   .. method:: feed_eof()
+StreamReaderProtocol
+--------------------
 
-      XXX
+.. class:: StreamReaderProtocol(stream_reader, client_connected_cb=None, loop=None)
 
-   .. method:: feed_data(data)
+    Trivial helper class to adapt between :class:`Protocol` and
+    :class:`StreamReader`. Sublclass of :class:`Protocol`.
 
-      XXX
+    *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.
 
-   .. method:: set_exception(exc)
+    (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.)
 
-      Set the exception.
+    .. method:: connection_made(transport)
 
-   .. method:: set_transport(transport)
+       XXX
 
-      Set the transport.
+    .. method:: connection_lost(exc)
 
-   .. method:: read(n=-1)
+       XXX
 
-      XXX
+    .. method:: data_received(data)
 
-      This method returns a :ref:`coroutine object <coroutine>`.
+       XXX
 
-   .. method:: readline()
+    .. method:: eof_received()
 
-      XXX
+       XXX
 
-      This method returns a :ref:`coroutine object <coroutine>`.
+    .. method:: pause_writing()
 
-   .. method:: readexactly(n)
+       XXX
 
-      XXX
+    .. method:: resume_writing()
 
-      This method returns a :ref:`coroutine object <coroutine>`.
+       XXX