From: Tom Christie <tom@tomchristie.com>
Date: Mon, 19 Aug 2019 15:09:11 +0000 (+0100)
Subject: Drop `raise_app_exceptions` Client argument. (#238)
X-Git-Tag: 0.7.2~26
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ef9fc0f3a70b35aa98fdc3756ecc87af94f884bc;p=thirdparty%2Fhttpx.git

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 5ecf5a62..424d397c 100644
--- 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 40bf0f18..fd86fb0c 100644
--- 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 8164b18e..23eebb0f 100644
--- 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 017eae18..60e0a18c 100644
--- 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.
     ```
     """