HTTPX offers a standard synchronous API by default, but also gives you the option of an async client if you need it.
Async is a concurrency model that is far more efficient than multi-threading, and can provide significant performance benefits and enable the use of 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.
Making Async requests
To make asynchronous requests, you'll need an
>>> async with httpx.AsyncClient() as client: >>> r = await client.get('https://www.example.com/') >>> r <Response [200 OK]>
Use IPython or Python 3.8+ with
python -m asyncio to try this code interactively, as they support executing
await expressions in the console.
If you're using an async client then there are a few bits of API that use async methods.
The request methods are all async, so you should use
response = await client.get(...) style for all of the following:
AsyncClient.request(method, url, ...)
Opening and closing clients
async with httpx.AsyncClient() if you want a context-managed client...
async with httpx.AsyncClient() as client: ...
await client.aclose() if you want to close a client explicitly:
client = httpx.AsyncClient() ... await client.aclose()
AsyncClient.stream(method, url, ...) method is an async context block.
>>> client = httpx.AsyncClient() >>> async with client.stream('GET', 'https://www.example.com/') as response: >>> async for chunk in response.aiter_bytes(): >>> ...
The async response streaming methods are:
Response.aread()- For conditionally reading a response inside a stream block.
Response.aiter_bytes()- For streaming the response content as bytes.
Response.aiter_text()- For streaming the response content as text.
Response.aiter_lines()- For streaming the response content as lines of text.
Response.aiter_raw()- For streaming the raw response bytes, without applying content decoding.
Response.aclose()- For closing the response. You don't usually need this, since
.streamblock close the response automatically on exit.
When sending a streaming request body with an
AsyncClient instance, you should use an async bytes generator instead of a bytes generator:
async def upload_bytes(): ... # yield byte content await client.post(url, data=upload_bytes())
Supported async environments
HTTPX supports either
trio as an async environment.
By default it will auto-detect which of those two to use as the backend for socket operations and concurrency primitives.
You can also explicitly select a backend by instantiating a client with the
client = httpx.AsyncClient(backend='auto') # Autodetection. The default case. client = httpx.AsyncClient(backend='asyncio') # Use asyncio as the backend. client = httpx.AsyncClient(backend='trio') # Use trio as the backend.
AsyncIO is Python's built-in library for writing concurrent code with the async/await syntax.
import asyncio import httpx async def main(): async with httpx.AsyncClient() as client: response = await client.get('https://www.example.com/') print(response) asyncio.run(main())
import httpx import trio async def main(): async with httpx.AsyncClient() as client: response = await client.get('https://www.example.com/') print(response) trio.run(main)
trio package must be installed to use the Trio backend.
Calling into Python Web Apps
httpx.Client allows you to call directly into WSGI web applications,
httpx.AsyncClient class allows you to call directly into ASGI web applications.
Let's take this Starlette application as an example:
from starlette.applications import Starlette from starlette.responses import HTMLResponse from starlette.routing import Route async def hello(): return HTMLResponse("Hello World!") app = Starlette(routes=[Route("/", hello)])
We can make requests directly against the application, like so:
>>> import httpx >>> async with httpx.AsyncClient(app=app) as client: ... r = await client.get('http://example/') ... assert r.status_code == 200 ... assert r.text == "Hello World!"
For some more complex cases you might need to customise the ASGI dispatch. This allows you to:
- Inspect 500 error responses rather than raise exceptions by setting
- Mount the ASGI application at a subpath by setting
- Use a given client address for requests by setting
# Instantiate a client that makes ASGI requests with a client IP of "184.108.40.206", # on port 123. dispatch = httpx.ASGIDispatch(app=app, client=("220.127.116.11", 123)) async with httpx.AsyncClient(dispatch=dispatch) as client: ...
See the ASGI documentation for more details on the
Unix Domain Sockets
The async client provides support for connecting through a unix domain socket via the
uds parameter. This is useful when making requests to a server that is bound to a socket file rather than an IP address.
Here's an example requesting the Docker Engine API:
import httpx async with httpx.AsyncClient(uds="/var/run/docker.sock") as client: # This request will connect through the socket file. resp = await client.get("http://localhost/version")
This functionality is not currently available in the synchronous client.