Better exception when missing optional dependencies (like Brotli)

[MicaelJarniac]

I've recently spent an unreasonable amount of time hunting a bug in my code, that ended up being that for whatever reason an API was returning br compressed data, and I didn't have the brotli optional installed.

The error I was getting was extremely unhelpful.

# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "httpx",
# ]
# ///


import httpx


async def test_brotli() -> None:
    async with httpx.AsyncClient(base_url="https://httpbin.io") as client:
        resp = await client.get(
            "/brotli",
        )
        resp.raise_for_status()
        print("status:", resp.status_code)
        print("content-type:", resp.headers.get("content-type"))
        print("content-encoding:", resp.headers.get("content-encoding"))
        print("first 16 bytes:", resp.content[:16])
        print(resp.json())


if __name__ == "__main__":
    import asyncio

    asyncio.run(test_brotli())

❯ uv run --script ./httpxme.py
status: 200
content-type: application/json; charset=utf-8
content-encoding: br
first 16 bytes: b'\x1b_\x01\x00deN_\xa3\x9a\xca!\xb9\x9f\xe3\x7f'
Traceback (most recent call last):
  File "/Users/micael/projects/playground/./httpxme.py", line 28, in <module>
    asyncio.run(test_brotli())
    ~~~~~~~~~~~^^^^^^^^^^^^^^^
  File "/Users/micael/.local/share/uv/python/cpython-3.13.3-macos-aarch64-none/lib/python3.13/asyncio/runners.py", line 195, in run
    return runner.run(main)
           ~~~~~~~~~~^^^^^^
  File "/Users/micael/.local/share/uv/python/cpython-3.13.3-macos-aarch64-none/lib/python3.13/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/Users/micael/.local/share/uv/python/cpython-3.13.3-macos-aarch64-none/lib/python3.13/asyncio/base_events.py", line 719, in run_until_complete
    return future.result()
           ~~~~~~~~~~~~~^^
  File "/Users/micael/projects/playground/./httpxme.py", line 22, in test_brotli
    print(resp.json())
          ~~~~~~~~~^^
  File "/Users/micael/.cache/uv/environments-v2/httpxme-b8dc774a8de1adab/lib/python3.13/site-packages/httpx/_models.py", line 832, in json
    return jsonlib.loads(self.content, **kwargs)
           ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/micael/.local/share/uv/python/cpython-3.13.3-macos-aarch64-none/lib/python3.13/json/__init__.py", line 341, in loads
    s = s.decode(detect_encoding(s), 'surrogatepass')
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa3 in position 8: invalid start byte

What would help is if the error was like MissingDependency: 'br' encoded content received, but 'brotli' dependency not installed or something along those lines.