Document exceptions (#1138)

* Document exceptions

* Update exceptions.md

docs/exceptions.md

@@ -0,0 +1,176 @@
+# Exceptions
+
+## Request and Response exceptions
+
+The most important exception classes in HTTPX are `RequestError` and `HTTPStatusError`.
+
+The `RequestError` class is a superclass that encompasses any exception that occurs
+while issuing an HTTP request. These exceptions include a `.request` attribute.
+
+```python
+try:
+    response = httpx.get("https://www.example.com/")
+except httpx.RequestError as exc:
+    print(f"An error occured while requesting {exc.request.url!r}.")
+```
+
+The `HTTPStatusError` class is raised by `response.raise_for_status()` on 4xx and 5xx responses.
+These exceptions include both a `.request` and a `.response` attribute.
+
+```python
+response = httpx.get("https://www.example.com/")
+try:
+    response.raise_for_status()
+except httpx.HTTPStatusError as exc:
+    print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
+```
+
+There is also a base class `HTTPError` that includes both of these categories, and can be used
+to catch either failed requests, or 4xx and 5xx responses.
+
+You can either use this base class to catch both categories...
+
+```python
+try:
+    response = httpx.get("https://www.example.com/")
+    response.raise_for_status()
+except httpx.HTTPError as exc:
+    print(f"Error while requesting {exc.request.url!r}.")
+```
+
+Or handle each case explicitly...
+
+```python
+try:
+    response = httpx.get("https://www.example.com/")
+    response.raise_for_status()
+except httpx.RequestError as exc:
+    print(f"An error occured while requesting {exc.request.url!r}.")
+except httpx.HTTPStatusError as exc:
+    print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
+```
+
+---
+
+## The exception hierarchy
+
+* HTTPError
+    * RequestError
+        * TransportError
+            * TimeoutException
+                * ConnectTimeout
+                * ReadTimeout
+                * WriteTimeout
+                * PoolTimeout
+            * NetworkError
+                * ConnectError
+                * ReadError
+                * WriteError
+                * CloseError
+            * ProtocolError
+                * LocalProtocolError
+                * RemoteProtocolError
+            * ProxyError
+            * UnsupportedProtocol
+        * DecodingError
+        * TooManyRedirects
+        * RequestBodyUnavailable
+    * HTTPStatusError
+* NotRedirectResponse
+* CookieConflict
+* StreamError
+    * StreamConsumed
+    * ResponseNotRead
+    * RequestNotRead
+    * ResponseClosed
+
+---
+
+## Exception classes
+
+::: httpx.HTTPError
+    :docstring:
+
+::: httpx.RequestError
+    :docstring:
+
+::: httpx.TransportError
+    :docstring:
+
+::: httpx.TimeoutException
+    :docstring:
+
+::: httpx.ConnectTimeout
+    :docstring:
+
+::: httpx.ReadTimeout
+    :docstring:
+
+::: httpx.WriteTimeout
+    :docstring:
+
+::: httpx.PoolTimeout
+    :docstring:
+
+::: httpx.NetworkError
+    :docstring:
+
+::: httpx.ConnectError
+    :docstring:
+
+::: httpx.ReadError
+    :docstring:
+
+::: httpx.WriteError
+    :docstring:
+
+::: httpx.CloseError
+    :docstring:
+
+::: httpx.ProtocolError
+    :docstring:
+
+::: httpx.LocalProtocolError
+    :docstring:
+
+::: httpx.RemoteProtocolError
+    :docstring:
+
+::: httpx.ProxyError
+    :docstring:
+
+::: httpx.UnsupportedProtocol
+    :docstring:
+
+::: httpx.DecodingError
+    :docstring:
+
+::: httpx.TooManyRedirects
+    :docstring:
+
+::: httpx.RequestBodyUnavailable
+    :docstring:
+
+::: httpx.HTTPStatusError
+    :docstring:
+
+::: httpx.NotRedirectResponse
+    :docstring:
+
+::: httpx.CookieConflict
+    :docstring:
+
+::: httpx.StreamError
+    :docstring:
+
+::: httpx.StreamConsumed
+    :docstring:
+
+::: httpx.ResponseNotRead
+    :docstring:
+
+::: httpx.RequestNotRead
+    :docstring:
+
+::: httpx.ResponseClosed
+    :docstring:

httpx/_exceptions.py

@@ -45,15 +45,17 @@ class HTTPError(Exception):
     Base class for `RequestError` and `HTTPStatusError`.
 
     Useful for `try...except` blocks when issuing a request,
-    and then calling .raise_for_status().
+    and then calling `.raise_for_status()`.
 
     For example:
 
+    ```
     try:
         response = httpx.get("https://www.example.com")
         response.raise_for_status()
     except httpx.HTTPError as exc:
         print(f"HTTP Exception for {exc.request.url} - {exc.message}")
+    ```
     """
 
     def __init__(self, message: str, *, request: "Request") -> None:
@@ -72,7 +74,9 @@ class RequestError(HTTPError):
 
 class TransportError(RequestError):
     """
-    Base class for all exceptions that are mapped from the httpcore API.
+    Base class for all exceptions that occur at the level of the Transport API.
+
+    All of these exceptions also have an equivelent mapping in `httpcore`.
     """
 
 
@@ -151,7 +155,7 @@ class CloseError(NetworkError):
 
 class ProxyError(TransportError):
     """
-    An error occurred while proxying a request.
+    An error occurred while establishing a proxy connection.
     """
 
 
@@ -192,7 +196,7 @@ class RemoteProtocolError(ProtocolError):
 
 class DecodingError(RequestError):
     """
-    Decoding of the response failed.
+    Decoding of the response failed, due to a malformed encoding.
     """
 
 
@@ -214,7 +218,7 @@ class RequestBodyUnavailable(RequestError):
 
 class HTTPStatusError(HTTPError):
     """
-    Response sent an error HTTP status.
+    The response had an error HTTP status of 4xx or 5xx.
 
     May be raised when calling `response.raise_for_status()`
     """

mkdocs.yml

@@ -18,6 +18,7 @@ nav:
     - Environment Variables: 'environment_variables.md'
     - Requests Compatibility: 'compatibility.md'
     - Developer Interface: 'api.md'
+    - Exceptions: 'exceptions.md'
     - Third Party Packages: 'third-party-packages.md'
     - Contributing: 'contributing.md'