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

diff --git a/docs/advanced.md b/docs/advanced.md
index 5ecf5a62c18e4b6e91bb2fab1821434f06c64060..424d397cf5455ec64c136e451bb482a2201a1620 100644 (file)
--- a/docs/advanced.md
+++ b/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

diff --git a/httpx/client.py b/httpx/client.py
index 40bf0f18a9ded5a2332997c6acdbe721edd07a7d..fd86fb0c8385e21bc09802faaf06564371494668 100644 (file)
--- a/httpx/client.py
+++ b/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(

diff --git a/httpx/dispatch/asgi.py b/httpx/dispatch/asgi.py
index 8164b18e229731e7c9067fa02a6e051caed818ff..23eebb0fc94da21dbdcc0074875501feaa78a381 100644 (file)
--- a/httpx/dispatch/asgi.py
+++ b/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.
     ```
     """
 

diff --git a/httpx/dispatch/wsgi.py b/httpx/dispatch/wsgi.py
index 017eae18df66851f216155e2e90aff96f7157d5f..60e0a18c7942030a3dcaf19b690767c139450123 100644 (file)
--- a/httpx/dispatch/wsgi.py
+++ b/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.
     ```
     """