AsyncClient

The asynchronous HTTP client for use with asyncio.

AsyncClient

AsyncClient(*args, max_concurrency: int | None = DEFAULT_MAX_CONCURRENCY, **kwargs)

An asynchronous HTTP client for use with asyncio.

AsyncClient wraps the synchronous Client using asyncio.run_in_executor(), providing an async interface while leveraging the Rust implementation's performance.

Example

Basic usage:

import asyncio
import httpr

async def main():
    async with httpr.AsyncClient() as client:
        response = await client.get("https://httpbin.org/get")
        print(response.json())

asyncio.run(main())

Concurrent requests:

import asyncio
import httpr

async def main():
    async with httpr.AsyncClient() as client:
        tasks = [
            client.get("https://httpbin.org/get"),
            client.get("https://httpbin.org/ip"),
        ]
        responses = await asyncio.gather(*tasks)
        for response in responses:
            print(response.json())

asyncio.run(main())

Note

AsyncClient runs synchronous Rust code in a thread executor. It provides concurrency benefits for I/O-bound tasks but is not native async I/O. max_concurrency sizes that executor and therefore caps how many requests can be in flight at once.

Initialize an async HTTP client.

Accepts the same parameters as Client, plus:

Parameters:

Name	Type	Description	Default
max_concurrency	int | None	Maximum number of requests in flight at once, i.e. the size of this client's thread pool. Defaults to 64. Threads are created lazily, so an idle client costs nothing. Pass None to dispatch on asyncio's default executor instead -- note that this shares a pool with asyncio.to_thread and every other run_in_executor(None) caller in the application, and that CPython sizes it at min(32, cpu_count + 4).	DEFAULT_MAX_CONCURRENCY

request async

request(method: HttpMethod, url: str, **kwargs: Unpack[RequestParams]) -> Response

Make an async HTTP request.

Parameters:

Name	Type	Description	Default
method	HttpMethod	HTTP method.	required
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters.	{}

Returns:

Type	Description
Response	Response object.

Example

response = await client.request("GET", "https://httpbin.org/get")

get async

get(url: str, **kwargs: Unpack[RequestParams]) -> Response

Make an async GET request.

Parameters:

Name	Type	Description	Default
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters.	{}

Returns:

Type	Description
Response	Response object.

Example

response = await client.get("https://httpbin.org/get")

head async

head(url: str, **kwargs: Unpack[RequestParams]) -> Response

Make an async HEAD request.

Parameters:

Name	Type	Description	Default
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters.	{}

Returns:

Type	Description
Response	Response object.

options async

options(url: str, **kwargs: Unpack[RequestParams]) -> Response

Make an async OPTIONS request.

Parameters:

Name	Type	Description	Default
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters.	{}

Returns:

Type	Description
Response	Response object.

delete async

delete(url: str, **kwargs: Unpack[RequestParams]) -> Response

Make an async DELETE request.

Parameters:

Name	Type	Description	Default
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters.	{}

Returns:

Type	Description
Response	Response object.

post async

post(url: str, **kwargs: Unpack[RequestParams]) -> Response

Make an async POST request.

Parameters:

Name	Type	Description	Default
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters including body options.	{}

Returns:

Type	Description
Response	Response object.

Example

response = await client.post(
    "https://httpbin.org/post",
    json={"key": "value"},
)

put async

put(url: str, **kwargs: Unpack[RequestParams]) -> Response

Make an async PUT request.

Parameters:

Name	Type	Description	Default
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters including body options.	{}

Returns:

Type	Description
Response	Response object.

patch async

patch(url: str, **kwargs: Unpack[RequestParams]) -> Response

Make an async PATCH request.

Parameters:

Name	Type	Description	Default
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters including body options.	{}

Returns:

Type	Description
Response	Response object.

stream async

stream(method: HttpMethod, url: str, **kwargs: Unpack[RequestParams]) -> AsyncIterator[StreamingResponse]

Make an async streaming HTTP request.

Returns an async context manager that yields a StreamingResponse for iterating over the response body in chunks.

Parameters:

Name	Type	Description	Default
method	HttpMethod	HTTP method.	required
url	str	Request URL.	required
**kwargs	Unpack[RequestParams]	Request parameters.	{}

Yields:

Name	Type	Description
StreamingResponse	AsyncIterator[StreamingResponse]	A response object that can be iterated.

Example

async with client.stream("GET", "https://example.com/large-file") as response:
    for chunk in response.iter_bytes():
        process(chunk)

Note

Iteration over the response is synchronous (uses iter_bytes, iter_text, iter_lines). The async part is initiating the request and entering the context manager.

aclose async

aclose()

Close the async client.

Example

client = httpr.AsyncClient()
try:
    response = await client.get("https://example.com")
finally:
    await client.aclose()