From: Tom Christie <tom@tomchristie.com>
Date: Wed, 1 May 2019 14:58:23 +0000 (+0100)
Subject: Updating docstrings
X-Git-Tag: 0.3.0~45
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5f8000fb352a23dc9f75217d92a86f583163151b;p=thirdparty%2Fhttpx.git

Updating docstrings
---

diff --git a/httpcore/decoders.py b/httpcore/decoders.py
index e58b8ee2..6b11060e 100644
--- a/httpcore/decoders.py
+++ b/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.
diff --git a/httpcore/exceptions.py b/httpcore/exceptions.py
index bae6b08d..55d377e0 100644
--- a/httpcore/exceptions.py
+++ b/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 StreamException(Exception):
+    """
+    The base class for stream exceptions.
 
-class StreamConsumed(Exception):
+    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.
     """
 
 
diff --git a/httpcore/interfaces.py b/httpcore/interfaces.py
index 644b1911..2ada76c8 100644
--- a/httpcore/interfaces.py
+++ b/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