Async Support

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.

Launching concurrent async tasks is far more resource efficient than spawning multiple threads. The Python interpreter should be able to comfortably handle switching between over 1000 concurrent tasks, while a sensible number of threads in a thread pool might be to enable around 10 or 20 concurrent threads.

Enabling Async support

If you're using async with Python's stdlib asyncio support, install the optional dependencies using:

pip install 'httpcore2[asyncio]'

Alternatively, if you're working with the Python trio package:

pip install 'httpcore2[trio]'

We highly recommend trio for async support. The trio project pioneered the principles of structured concurrency, and has a more carefully constrained API against which to work from.

API differences

When using async support, you need make sure to use an async connection pool class:

# The async variation of `httpcore2.ConnectionPool`
async with httpcore2.AsyncConnectionPool() as http:
    ...

Sending requests

Sending requests with the async version of httpcore2 requires the await keyword:

import asyncio
import httpcore2

async def main():
    async with httpcore2.AsyncConnectionPool() as http:
        response = await http.request("GET", "https://www.example.com/")


asyncio.run(main())

When including content in the request, the content must either be bytes or an async iterable yielding bytes.

Streaming responses

Streaming responses also require a slightly different interface to the sync version:

• with <pool>.stream(...) as response → async with <pool>.stream() as response.
• for chunk in response.iter_stream() → async for chunk in response.aiter_stream().
• response.read() → await response.aread().
• response.close() → await response.aclose()

For example:

import asyncio
import httpcore2


async def main():
    async with httpcore2.AsyncConnectionPool() as http:
        async with http.stream("GET", "https://www.example.com/") as response:
            async for chunk in response.aiter_stream():
                print(f"Downloaded: {chunk}")


asyncio.run(main())

Pool lifespans

When using httpcore2 in an async environment it is strongly recommended that you instantiate and use connection pools using the context managed style:

async with httpcore2.AsyncConnectionPool() as http:
    ...

To benefit from connection pooling it is recommended that you instantiate a single connection pool in this style, and pass it around throughout your application.

If you do want to use a connection pool without this style then you'll need to ensure that you explicitly close the pool once it is no longer required:

try:
    http = httpcore2.AsyncConnectionPool()
    ...
finally:
    await http.aclose()

This is a little different to the threaded context, where it's okay to simply instantiate a globally available connection pool, and then allow Python's garbage collection to deal with closing any connections in the pool, once the __del__ method is called.

The reason for this difference is that asynchronous code is not able to run within the context of the synchronous __del__ method, so there is no way for connections to be automatically closed at the point of garbage collection. This can lead to unterminated TCP connections still remaining after the Python interpreter quits.

Supported environments

HTTPX supports either asyncio or trio as an async environment.

It will auto-detect which of those two to use as the backend for socket operations and concurrency primitives.

AsyncIO

AsyncIO is Python's built-in library for writing concurrent code with the async/await syntax.

Let's take a look at sending several outgoing HTTP requests concurrently, using asyncio:

import asyncio
import httpcore2
import time


async def download(http, year):
    await http.request("GET", f"https://en.wikipedia.org/wiki/{year}")


async def main():
    async with httpcore2.AsyncConnectionPool() as http:
        started = time.time()
        # Here we use `asyncio.gather()` in order to run several tasks concurrently...
        tasks = [download(http, year) for year in range(2000, 2020)]
        await asyncio.gather(*tasks)
        complete = time.time()

        for connection in http.connections:
            print(connection)
        print("Complete in %.3f seconds" % (complete - started))


asyncio.run(main())

Trio

Trio is an alternative async library, designed around the the principles of structured concurrency.

import httpcore2
import trio
import time


async def download(http, year):
    await http.request("GET", f"https://en.wikipedia.org/wiki/{year}")


async def main():
    async with httpcore2.AsyncConnectionPool() as http:
        started = time.time()
        async with trio.open_nursery() as nursery:
            for year in range(2000, 2020):
                nursery.start_soon(download, http, year)
        complete = time.time()

        for connection in http.connections:
            print(connection)
        print("Complete in %.3f seconds" % (complete - started))


trio.run(main)

AnyIO

AnyIO is an asynchronous networking and concurrency library that works on top of either asyncio or trio. It blends in with native libraries of your chosen backend (defaults to asyncio).

The anyio library is designed around the the principles of structured concurrency, and brings many of the same correctness and usability benefits that Trio provides, while interoperating with existing asyncio libraries.

import httpcore2
import anyio
import time


async def download(http, year):
    await http.request("GET", f"https://en.wikipedia.org/wiki/{year}")


async def main():
    async with httpcore2.AsyncConnectionPool() as http:
        started = time.time()
        async with anyio.create_task_group() as task_group:
            for year in range(2000, 2020):
                task_group.start_soon(download, http, year)
        complete = time.time()

        for connection in http.connections:
            print(connection)
        print("Complete in %.3f seconds" % (complete - started))


anyio.run(main)

Reference

httpcore2.AsyncConnectionPool

connections: list[AsyncConnectionInterface]

>>> pool.connections
[
    <AsyncHTTPConnection ['https://example.com:443', HTTP/1.1, ACTIVE, Request Count: 6]>,
    <AsyncHTTPConnection ['https://example.com:443', HTTP/1.1, IDLE, Request Count: 9]> ,
    <AsyncHTTPConnection ['http://example.com:80', HTTP/1.1, IDLE, Request Count: 1]>,
]

__init__(
    ssl_context: SSLContext | None = None,
    proxy: Proxy | None = None,
    max_connections: int | None = 10,
    max_keepalive_connections: int | None = None,
    keepalive_expiry: float | None = None,
    http1: bool = True,
    http2: bool = False,
    retries: int = 0,
    local_address: str | None = None,
    uds: str | None = None,
    network_backend: AsyncNetworkBackend | None = None,
    socket_options: Iterable[SOCKET_OPTION] | None = None,
) -> None

handle_async_request(request: Request) -> Response