Make async dependencies optional.

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased
 
+* Added `httpx[asyncio]` and `httpx[trio]` extras.
+* Default support for `asyncio` has been removed, you need to explicitly install `httpx[asyncio]`.
 * The deprecated `proxies` argument has now been removed.
 * The deprecated `app` argument has now been removed.
 * The `URL.raw` property has now been removed.

README.md

@@ -97,10 +97,12 @@ Install with pip:
 $ pip install httpx
 ```
 
-Or, to include the optional HTTP/2 support, use:
+There are also a number of optional dependancies.
+
+For example to include asyncio and HTTP/2 support, use:
 
 ```shell
-$ pip install httpx[http2]
+$ pip install 'httpx[asyncio,http2]'
 ```
 
 HTTPX requires Python 3.8+.
@@ -129,15 +131,17 @@ The HTTPX project relies on these excellent libraries:
   * `h11` - HTTP/1.1 support.
 * `certifi` - SSL certificates.
 * `idna` - Internationalized domain name support.
-* `sniffio` - Async library autodetection.
 
 As well as these optional installs:
 
-* `h2` - HTTP/2 support. *(Optional, with `httpx[http2]`)*
-* `socksio` - SOCKS proxy support. *(Optional, with `httpx[socks]`)*
-* `rich` - Rich terminal support. *(Optional, with `httpx[cli]`)*
-* `click` - Command line client support. *(Optional, with `httpx[cli]`)*
-* `brotli` or `brotlicffi` - Decoding for "brotli" compressed responses. *(Optional, with `httpx[brotli]`)*
+* `anyio` - Async support for `asyncio`. *(Optional, with `httpx['asyncio']`)*
+* `trio` - Async support for `trio`. *(Optional, with `httpx['trio']`)*
+* `h2` - HTTP/2 support. *(Optional, with `httpx['http2']`)*
+* `socksio` - SOCKS proxy support. *(Optional, with `httpx['socks']`)*
+* `click` - Command line client support. *(Optional, with `httpx['cli']`)*
+* `rich` - Command line client support. *(Optional, with `httpx['cli']`)*
+* `pygments` - Command line client support. *(Optional, with `httpx['cli']`)*
+* `brotli` or `brotlicffi` - Decoding for "brotli" compressed responses. *(Optional, with `httpx['brotli']`)*
 * `zstandard` - Decoding for "zstd" compressed responses. *(Optional, with `httpx[zstd]`)*
 
 A huge amount of credit is due to `requests` for the API layout that

docs/async.md

@@ -10,6 +10,24 @@ long-lived network connections such as WebSockets.
 If you're working with an async web framework then you'll also want to use an
 async client for sending outgoing HTTP requests.
 
+## Enabling Async support
+
+To enable async support you'll need to install some additional dependencies:
+
+If you're using Python's [standard `asyncio` support](https://docs.python.org/3/library/asyncio.html) then:
+
+```shell
+$ pip install 'httpx[asyncio]'
+```
+
+Or, if you're working with the [`trio` third party package](https://trio.readthedocs.io/en/stable/):
+
+```shell
+$ pip install 'httpx[trio]'
+```
+
+We highly recommend `trio` for async support. The `trio` project [pioneered the principles of structured concurrency](https://en.wikipedia.org/wiki/Structured_concurrency), and has a more carefully constrained API against which to work from.
+
 ## Making Async requests
 
 To make asynchronous requests, you'll need an `AsyncClient`.

httpx/_transports/default.py

@@ -277,6 +277,14 @@ def __init__(
         retries: int = 0,
         socket_options: typing.Iterable[SOCKET_OPTION] | None = None,
     ) -> None:
+        try:
+            import sniffio  # noqa: F401
+        except ImportError:  # pragma: nocover
+            raise RuntimeError(
+                "Using httpx in async mode, but neither "
+                "'httpx[asyncio]' or 'httpx[trio]' is installed."
+            )
+
         ssl_context = create_ssl_context(verify=verify, cert=cert, trust_env=trust_env)
         proxy = Proxy(url=proxy) if isinstance(proxy, (str, URL)) else proxy
 

pyproject.toml

@@ -29,30 +29,35 @@ classifiers = [
 ]
 dependencies = [
     "certifi",
-    "httpcore==1.*",
-    "anyio",
+    "httpcore>=1.0.0,<2.0.0",
     "idna",
 ]
 dynamic = ["readme", "version"]
 
 [project.optional-dependencies]
+asyncio = [
+    "httpcore[asyncio]",
+]
 brotli = [
     "brotli; platform_python_implementation == 'CPython'",
     "brotlicffi; platform_python_implementation != 'CPython'",
 ]
 cli = [
-    "click==8.*",
-    "pygments==2.*",
-    "rich>=10,<14",
+    "click>=8.0.0,<9.0.0",
+    "pygments>=2.0.0,<3.0.0",
+    "rich>=10.0.0,<14.0.0",
 ]
 http2 = [
-    "h2>=3,<5",
+    "httpcore[http2]",
 ]
 socks = [
-    "socksio==1.*",
+    "httpcore[socks]",
+]
+trio = [
+    "httpcore[trio]",
 ]
 zstd = [
-  "zstandard>=0.18.0",
+  "zstandard>=0.18.0,<1.0.0",
 ]
 
 [project.scripts]

requirements.txt

@@ -2,7 +2,7 @@
 # On the other hand, we're not pinning package dependencies, because our tests
 # needs to pass with the latest version of the packages.
 # Reference: https://github.com/encode/httpx/pull/1721#discussion_r661241588
--e .[brotli,cli,http2,socks,zstd]
+-e .[asyncio,brotli,cli,http2,socks,trio,zstd]
 
 # Optional charset auto-detection
 # Used in our test cases
@@ -23,7 +23,5 @@ cryptography==43.0.1
 mypy==1.11.2
 pytest==8.3.2
 ruff==0.6.3
-trio==0.26.2
-trio-typing==0.10.0
 trustme==1.1.0
 uvicorn==0.30.6