Updating docstrings

httpcore/decoders.py

@@ -23,6 +23,10 @@ class Decoder:
 
 
 class IdentityDecoder(Decoder):
+    """
+    Handle unencoded data.
+    """
+
     def decode(self, data: bytes) -> bytes:
         return data
 
@@ -80,8 +84,7 @@ class BrotliDecoder(Decoder):
     """
     Handle 'brotli' decoding.
 
-    Requires `pip install brotlipy`.
-    See: https://brotlipy.readthedocs.io/
+    Requires `pip install brotlipy`. See: https://brotlipy.readthedocs.io/
     """
 
     def __init__(self) -> None:
@@ -111,7 +114,7 @@ class MultiDecoder(Decoder):
 
     def __init__(self, children: typing.Sequence[Decoder]) -> None:
         """
-        children should be a sequence of decoders in the order in which
+        'children' should be a sequence of decoders in the order in which
         each was applied.
         """
         # Note that we reverse the order for decoding.

httpcore/exceptions.py

@@ -40,6 +40,12 @@ class ProtocolError(Exception):
     """
 
 
+class DecodingError(Exception):
+    """
+    Decoding of the response failed.
+    """
+
+
 # Redirect exceptions...
 
 
@@ -68,33 +74,36 @@ class RedirectLoop(RedirectError):
     """
 
 
-# Response exceptions...
+# Stream exceptions...
 
 
-class StreamConsumed(Exception):
+class StreamException(Exception):
+    """
+    The base class for stream exceptions.
+
+    The developer made an error in accessing the request stream in
+    an invalid way.
+    """
+
+
+class StreamConsumed(StreamException):
     """
     Attempted to read or stream response content, but the content has already
     been streamed.
     """
 
 
-class ResponseNotRead(Exception):
+class ResponseNotRead(StreamException):
     """
     Attempted to access response content, without having called `read()`
     after a streaming response.
     """
 
 
-class ResponseClosed(Exception):
+class ResponseClosed(StreamException):
     """
     Attempted to read or stream response content, but the request has been
-    closed without loading the body.
-    """
-
-
-class DecodingError(Exception):
-    """
-    Decoding of the response failed.
+    closed.
     """
 
 

httpcore/interfaces.py

@@ -8,6 +8,14 @@ OptionalTimeout = typing.Optional[TimeoutConfig]
 
 
 class Adapter:
+    """
+    The base class for all adapter or dispatcher classes.
+
+    Stubs out the interface, as well as providing a `.request()` convienence
+    implementation, to make it easy to use or test stand-alone adapters,
+    without requiring a complete `Client` instance.
+    """
+
     async def request(
         self,
         method: str,
@@ -44,11 +52,23 @@ class Adapter:
 
 
 class BaseReader:
+    """
+    A stream reader. Abstracts away any asyncio-specfic interfaces
+    into a more generic base class, that we can use with alternate
+    backend, or for stand-alone test cases.
+    """
+
     async def read(self, n: int, timeout: OptionalTimeout = None) -> bytes:
         raise NotImplementedError()  # pragma: no cover
 
 
 class BaseWriter:
+    """
+    A stream writer. Abstracts away any asyncio-specfic interfaces
+    into a more generic base class, that we can use with alternate
+    backend, or for stand-alone test cases.
+    """
+
     def write_no_block(self, data: bytes) -> None:
         raise NotImplementedError()  # pragma: no cover
 
@@ -60,6 +80,12 @@ class BaseWriter:
 
 
 class BasePoolSemaphore:
+    """
+    A semaphore for use with connection pooling.
+
+    Abstracts away any asyncio-specfic interfaces.
+    """
+
     async def acquire(self) -> None:
         raise NotImplementedError()  # pragma: no cover