Repository: aio-libs/aiohttp

Issue:
Explicitly document streams API
http://aiohttp.readthedocs.io/en/stable/api.html looks like a piece of garbage.

Especially when I look on streaming API
http://aiohttp.readthedocs.io/en/stable/api.html#module-aiohttp.streams

It mixes native private methods like `feed_eof()` and `feed_data()` with decided to be used by top-level programmer like `.read_any` etc.
Moreover it doesn't suggest to use `async for` for iterating over incoming data and so on.

The doc should get rid of autodoc usage and switch to explicit documentation writing (as Python itself does).

The far blue sky goal is getting rid of autodoc usage at all for the project.



Discussion:

Resolving patch:
diff --git a/aiohttp/client_reqrep.py b/aiohttp/client_reqrep.py
--- a/aiohttp/client_reqrep.py
+++ b/aiohttp/client_reqrep.py
@@ -284,7 +284,8 @@ def update_body_from_data(self, data, skip_auto_headers):
             if hdrs.CONTENT_LENGTH not in self.headers and not self.chunked:
                 self.headers[hdrs.CONTENT_LENGTH] = str(len(self.body))
 
-        elif isinstance(data, (asyncio.StreamReader, streams.DataQueue)):
+        elif isinstance(data, (asyncio.StreamReader, streams.StreamReader,
+                               streams.DataQueue)):
             self.body = data
 
         elif asyncio.iscoroutine(data):
@@ -427,7 +428,8 @@ def write_bytes(self, request, reader):
                             'Bytes object is expected, got: %s.' %
                             type(result))
 
-            elif isinstance(self.body, asyncio.StreamReader):
+            elif isinstance(self.body, (asyncio.StreamReader,
+                                        streams.StreamReader)):
                 request.transport.set_tcp_nodelay(True)
                 chunk = yield from self.body.read(streams.DEFAULT_LIMIT)
                 while chunk:
diff --git a/aiohttp/streams.py b/aiohttp/streams.py
--- a/aiohttp/streams.py
+++ b/aiohttp/streams.py
@@ -65,8 +65,8 @@ def iter_any(self):
             return AsyncStreamIterator(self.readany)
 
 
-class StreamReader(asyncio.StreamReader, AsyncStreamReaderMixin):
-    """An enhancement of :class:`asyncio.StreamReader`.
+class StreamReader(AsyncStreamReaderMixin):
+    """An enhancement of asyncio.StreamReader.
 
     Supports asynchronous iteration by line, chunk or as available::
 
@@ -77,8 +77,6 @@ class StreamReader(asyncio.StreamReader, AsyncStreamReaderMixin):
         async for slice in reader.iter_any():
             ...
 
-    .. automethod:: AsyncStreamReaderMixin.iter_chunked
-    .. automethod:: AsyncStreamReaderMixin.iter_any
     """
 
     total_bytes = 0
@@ -238,7 +236,7 @@ def readline(self):
                 offset = self._buffer_offset
                 ichar = self._buffer[0].find(b'\n', offset) + 1
                 # Read from current offset to found b'\n' or to the end.
-                data = self._read_nowait(ichar - offset if ichar else 0)
+                data = self._read_nowait(ichar - offset if ichar else -1)
                 line.append(data)
                 line_size += len(data)
                 if ichar:
@@ -302,7 +300,7 @@ def readany(self):
         if not self._buffer and not self._eof:
             yield from self._wait('readany')
 
-        return self._read_nowait()
+        return self._read_nowait(-1)
 
     @asyncio.coroutine
     def readexactly(self, n):
@@ -321,7 +319,12 @@ def readexactly(self, n):
 
         return b''.join(blocks)
 
-    def read_nowait(self, n=None):
+    def read_nowait(self, n=-1):
+        # default was changed to be consistent with .read(-1)
+        #
+        # I believe the most users don't know about the method and
+        # they are not affected.
+        assert n is not None, "n should be -1"
         if self._exception is not None:
             raise self._exception
 
@@ -331,13 +334,13 @@ def read_nowait(self, n=None):
 
         return self._read_nowait(n)
 
-    def _read_nowait(self, n=None):
+    def _read_nowait(self, n):
         if not self._buffer:
             return EOF_MARKER
 
         first_buffer = self._buffer[0]
         offset = self._buffer_offset
-        if n and len(first_buffer) - offset > n:
+        if n != -1 and len(first_buffer) - offset > n:
             data = first_buffer[offset:offset + n]
             self._buffer_offset += n
 


Test patch: