[Python-checkins] cpython: asyncio.docs: Improve documentation of Streams. Issue #20696.

[yury.selivanov]

http://hg.python.org/cpython/rev/1c35d3114ea1
changeset:   89306:1c35d3114ea1
user:        Yury Selivanov <yselivanov at sprymix.com>
date:        Thu Feb 20 14:10:02 2014 -0500
summary:
  asyncio.docs: Improve documentation of Streams. Issue #20696.

files:
  Doc/library/asyncio-stream.rst |  72 +++++++++++++--------
  1 files changed, 43 insertions(+), 29 deletions(-)


diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -34,7 +34,7 @@
 
 .. function:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, **kwds)
 
-   Start a socket server, call back for each client connected.
+   Start a socket server, with a callback for each client connected.
 
    The first parameter, *client_connected_cb*, takes two parameters:
    *client_reader*, *client_writer*.  *client_reader* is a
@@ -58,6 +58,29 @@
 
    This function returns a :ref:`coroutine object <coroutine>`.
 
+.. function:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
+
+   A wrapper for :meth:`~BaseEventLoop.create_unix_connection()` returning
+   a (reader, writer) pair.
+
+   See :func:`open_connection` for information about return value and other
+   details.
+
+   This function returns a :ref:`coroutine object <coroutine>`.
+
+   Availability: UNIX.
+
+.. function:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, **kwds)
+
+   Start a UNIX Domain Socket server, with a callback for each client connected.
+
+   See :func:`start_server` for information about return value and other
+   details.
+
+   This function returns a :ref:`coroutine object <coroutine>`.
+
+   Availability: UNIX.
+
 
 StreamReader
 ============
@@ -70,11 +93,12 @@
 
    .. method:: feed_eof()
 
-      XXX
+      Acknowledge the EOF.
 
    .. method:: feed_data(data)
 
-      XXX
+      Feed *data* bytes in the internal buffer.  Any operations waiting
+      for the data will be resumed.
 
    .. method:: set_exception(exc)
 
@@ -86,13 +110,23 @@
 
    .. method:: read(n=-1)
 
-      XXX
+      Read up to *n* bytes.  If *n* is not provided, or set to ``-1``,
+      read until EOF and return all read bytes.
+
+      If the EOF was received and the internal buffer is empty,
+      return an empty ``bytes`` object.
 
       This method returns a :ref:`coroutine object <coroutine>`.
 
    .. method:: readline()
 
-      XXX
+      Read one line, where "line" is a sequence of bytes ending with ``\n``.
+
+      If EOF is received, and ``\n`` was not found, the method will
+      return the partial read bytes.
+
+      If the EOF was received and the internal buffer is empty,
+      return an empty ``bytes`` object.
 
       This method returns a :ref:`coroutine object <coroutine>`.
 
@@ -105,6 +139,10 @@
 
       This method returns a :ref:`coroutine object <coroutine>`.
 
+   .. method:: at_eof()
+
+      Return ``True`` if the buffer is empty and :meth:`feed_eof` was called.
+
 
 StreamWriter
 ============
@@ -186,30 +224,6 @@
     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
-
 
 IncompleteReadError
 ===================

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