Drop raise_app_exceptions Client argument. (#238)

* Drop `raise_app_exceptions` keyword argument
* Improve docstrings for WSGIDispatch and ASGIDispatch
* Add docs for fine grained WSGI/ASGI control

docs/advanced.md

@@ -42,6 +42,21 @@ assert r.status_code == 200
 assert r.text == "Hello World!"
 ```
 
+For some more complex cases you might need to customize the WSGI or ASGI
+dispatch. This allows you to:
+
+* Inspect 500 error responses, rather than raise exceptions, by setting `raise_app_exceptions=False`.
+* Mount the WSGI or ASGI application at a subpath, by setting `script_name` (WSGI) or `root_path` (ASGI).
+* Use a given the client address for requests, by setting `remote_addr` (WSGI) or `client` (ASGI).
+
+For example:
+
+```python
+# Instantiate a client that makes WSGI requests with a client IP of "1.2.3.4".
+dispatch = httpx.WSGIDispatch(app=app, remote_addr="1.2.3.4")
+client = httpx.Client(dispatch=dispatch)
+```
+
 ## .netrc Support
 
 HTTPX supports .netrc file. In `trust_env=True` cases, if auth parameter is

httpx/client.py

@@ -63,7 +63,6 @@ class BaseClient:
         base_url: URLTypes = None,
         dispatch: typing.Union[AsyncDispatcher, Dispatcher] = None,
         app: typing.Callable = None,
-        raise_app_exceptions: bool = True,
         backend: ConcurrencyBackend = None,
         trust_env: bool = None,
     ):
@@ -76,13 +75,9 @@ class BaseClient:
             param_count = len(inspect.signature(app).parameters)
             assert param_count in (2, 3)
             if param_count == 2:
-                dispatch = WSGIDispatch(
-                    app=app, raise_app_exceptions=raise_app_exceptions
-                )
+                dispatch = WSGIDispatch(app=app)
             else:
-                dispatch = ASGIDispatch(
-                    app=app, raise_app_exceptions=raise_app_exceptions
-                )
+                dispatch = ASGIDispatch(app=app)
 
         if dispatch is None:
             async_dispatch: AsyncDispatcher = ConnectionPool(

httpx/dispatch/asgi.py

@@ -29,6 +29,15 @@ class ASGIDispatch(AsyncDispatcher):
         client=("1.2.3.4", 123)
     )
     client = httpx.Client(dispatch=dispatch)
+
+    Arguments:
+
+    * `app` - The ASGI application.
+    * `raise_app_exceptions` - Boolean indicating if exceptions in the application
+       should be raised. Default to `True`. Can be set to `False` for use cases
+       such as testing the content of a client 500 response.
+    * `root_path` - The root path on which the ASGI application should be mounted.
+    * `client` - A two-tuple indicating the client IP and port of incoming requests.
     ```
     """
 

httpx/dispatch/wsgi.py

@@ -29,6 +29,16 @@ class WSGIDispatch(Dispatcher):
         remote_addr="1.2.3.4"
     )
     client = httpx.Client(dispatch=dispatch)
+
+
+    Arguments:
+
+    * `app` - The ASGI application.
+    * `raise_app_exceptions` - Boolean indicating if exceptions in the application
+       should be raised. Default to `True`. Can be set to `False` for use cases
+       such as testing the content of a client 500 response.
+    * `script_name` - The root path on which the ASGI application should be mounted.
+    * `remote_addr` - A string indicating the client IP of incoming requests.
     ```
     """