Improve documentation

httplib/retriever.py

@@ -62,13 +62,20 @@ class PreambleRetriever(Retriever):
     """
     Retriever instance for retrieving the start-line and headers of an HTTP message.
     """
+
     client: HTTPSocket
     _buffer: []
 
     @property
     def buffer(self):
+        """
+        Returns a copy of the internal buffer.
+        Clears the internal buffer afterwards.
+
+        @return: A list of the buffered lines.
+        """
         tmp_buffer = self._buffer
-        self._buffer = []
+        self._buffer.clear()
 
         return tmp_buffer
 
@@ -87,7 +94,7 @@ class PreambleRetriever(Retriever):
         while True:
             self._buffer.append(line)
 
-            if line in ("\r\n", "\n", ""):
+            if line in ("\r\n", "\r", "\n", ""):
                 return line
 
             yield line
@@ -140,8 +147,8 @@ class ContentLengthRetriever(Retriever):
 
 class RawRetriever(Retriever):
     """
-    Retriever instance for retrieve a message body without any length specifier or encoding.
-    This retriever will keep waiting until a timeout occurs or the connection is disconnected.
+    Retriever instance for retrieving a message body without any length specifier or encoding.
+    This retriever will keep waiting until a timeout occurs, or the connection is disconnected.
     """
 
     def retrieve(self):
@@ -161,6 +168,7 @@ class ChunkedRetriever(Retriever):
         """
         Returns an iterator of the received message bytes.
         The size of each iteration is not necessarily constant.
+
         @raise IncompleteResponse: if the connection is closed or timed out before receiving the complete payload.
         @raise InvalidResponse: if the length of a chunk could not be determined.
         """
@@ -184,6 +192,12 @@ class ChunkedRetriever(Retriever):
             raise IncompleteResponse("Connection closed before receiving the complete payload!")
 
     def __get_chunk_size(self):
+        """
+        Returns the next chunk size.
+
+        @return: The chunk size in bytes
+        @raise InvalidResponse: If an error occured when parsing the chunk size.
+        """
         line = self.client.read_line()
         sep_pos = line.find(";")
         if sep_pos >= 0:
@@ -192,4 +206,4 @@ class ChunkedRetriever(Retriever):
         try:
             return int(line, 16)
         except ValueError:
-            raise InvalidResponse()
+            raise InvalidResponse("Failed to parse chunk size")