Repository: encode/httpx

Issue:
Handle HEAD responses with Brotli decoder
Currently if you receive a response with `Content-Encoding: br` set and no body we get an error because Brotli doesn't like being called on an empty stream.

Discussion:
tomchristie: On reviewing this, I'm not sure my "More generally: we should make sure not to call any decoder if the body is empty." comment is the best - approach.

Your PR here fixes one case, but we'd also need to introduce the same for the streaming case.

It's probably more pragmatic for us to make sure that the brotli decoder implementation (and any others) all correctly deal with `""` inputs, and all correctly return `""` for the output in that case.
sethmlarson: Totally agree with Tom here. Decoders shouldn't explode on empty input. 
cansarigol: I added a [commit](https://github.com/encode/httpx/pull/237/commits/8f73ce73802e916526e8fc90d213636d17b07f12) Am I continuing with seen_data?
tomchristie: > Am I continuing with seen_data?

Please, yup.

The `httpx/models.py` file should not change as part of this PR, and the signature of `def decode(self, data: bytes)` should stay the same too.


Patch:
diff --git a/docs/advanced.md b/docs/advanced.md
index 5ecf5a6..424d397 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 40bf0f1..fd86fb0 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/decoders.py b/httpx/decoders.py
index bfa9654..3ae822b 100644
--- a/httpx/decoders.py
+++ b/httpx/decoders.py
@@ -98,8 +98,12 @@ class BrotliDecoder(Decoder):
             brotli is not None
         ), "The 'brotlipy' or 'brotli' library must be installed to use 'BrotliDecoder'"
         self.decompressor = brotli.Decompressor()
+        self.seen_data = False
 
     def decode(self, data: bytes) -> bytes:
+        if not data:
+            return b""
+        self.seen_data = True
         try:
             if hasattr(self.decompressor, "decompress"):
                 return self.decompressor.decompress(data)
@@ -108,6 +112,8 @@ class BrotliDecoder(Decoder):
             raise DecodingError from exc
 
     def flush(self) -> bytes:
+        if not self.seen_data:
+            return b""
         try:
             if hasattr(self.decompressor, "finish"):
                 self.decompressor.finish()
diff --git a/httpx/dispatch/asgi.py b/httpx/dispatch/asgi.py
index 8164b18..23eebb0 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 017eae1..60e0a18 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.
     ```
     """
 


Test patch:
diff --git a/tests/test_decoders.py b/tests/test_decoders.py
index 036a416..1b5d6e1 100644
--- a/tests/test_decoders.py
+++ b/tests/test_decoders.py
@@ -4,7 +4,13 @@ import brotli
 import pytest
 
 import httpx
-from httpx.decoders import TextDecoder
+from httpx.decoders import (
+    BrotliDecoder,
+    DeflateDecoder,
+    GZipDecoder,
+    IdentityDecoder,
+    TextDecoder,
+)
 
 
 def test_deflate():
@@ -79,6 +85,22 @@ def test_streaming():
     assert response.read() == body
 
 
+@pytest.mark.parametrize("header_value", (b"deflate", b"gzip", b"br", b"identity"))
+def test_empty_content(header_value):
+    headers = [(b"Content-Encoding", header_value)]
+    response = httpx.Response(200, headers=headers, content=b"")
+    assert response.content == b""
+
+
+@pytest.mark.parametrize(
+    "decoder", (BrotliDecoder, DeflateDecoder, GZipDecoder, IdentityDecoder)
+)
+def test_decoders_empty_cases(decoder):
+    instance = decoder()
+    assert instance.decode(b"") == b""
+    assert instance.flush() == b""
+
+
 @pytest.mark.parametrize("header_value", (b"deflate", b"gzip", b"br"))
 def test_decoding_errors(header_value):
     headers = [(b"Content-Encoding", header_value)]