Deferred sending
Prepare a request before choosing when or through which client it will be transmitted.
HTTPX · Class
Request
httpx.Request is HTTPX’s low-level model for constructing an HTTP request before transmission. It is useful when request preparation and sending need to be separate.
How it works
httpx.Request is a low-level request model: it stores the method, URL, headers, cookies, query parameters, body, and optional extensions. Build it when you need to prepare a request separately from transmission, then pass it to a client’s send() method; the request is sent as-is rather than being modified by the client.
Syntax
httpx.Request(method, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, extensions=None)Parameters
| Name | Type | Description |
|---|---|---|
method | str | HTTP method, such as GET, POST, PUT, PATCH, DELETE, OPTIONS, or HEAD. |
url | URL or str | Destination URL. |
content | bytes, str, or iterable of bytes | Raw request body content. |
data | Mapping or iterable | Form data. |
files | Mapping or iterable | Multipart upload files. |
json | Any | JSON-serializable request body. |
params | Mapping or iterable of two-tuples | Query parameters. |
headers | Mapping or iterable | HTTP headers. |
cookies | Mapping or iterable | Cookies. |
auth | Auth object or tuple | Authentication configuration. |
extensions | Mapping | Request extensions. |
Returns
A Request object representing the constructed HTTP request.
Key points
- Constructing a Request only prepares the model; transmission happens when a client sends it.
- A manually built request preserves its prepared state when passed to the sending API.
- Use explicit request construction when you need control over the exact request that leaves the client.
Common mistakes
- A Request does not receive the higher-level client preparation applied by convenience methods; review its final contents before sending it.
Example: Build and send a request
import asyncio
import httpx
async def main():
request = httpx.Request("GET", "https://example.org")
async with httpx.AsyncClient() as client:
response = await client.send(request)
print(response.status_code)
asyncio.run(main())Creates a request explicitly, then sends it through an asynchronous client.
When to use it
Precise request construction
Specify the exact method, URL, headers, query parameters, and body before dispatch.
Client-independent preparation
Pass a prepared request to synchronous or asynchronous client sending APIs.
Interview questions
QWhat is the distinction between constructing and sending a Request?
httpx.Request represents a prepared HTTP request, while Client.send() or AsyncClient.send() performs transmission. This separation lets code construct a request first and send it later.
Follow-up: How would you send one request asynchronously? Construct it with httpx.Request, create an AsyncClient, and await client.send(request).
QWhat does “sent as-is” imply for a Request?
The request is transmitted as-is and unmodified. Therefore, values that must be present in the outgoing request should be supplied when the Request is constructed.
Follow-up: How can client-wide behavior be applied instead? Use a client’s configuration or event hooks for behavior that belongs to the client layer, rather than assuming Request will add it.
QWhich kinds of data can be included when constructing a Request?
The constructor accepts method, URL, content, form data, files, JSON, query parameters, headers, cookies, authentication, and extensions according to the documented signature. However, several client-level controls are not constructor parameters.
Follow-up: Which controls are excluded? The documentation specifically excludes auth, timeout, follow_redirects, mounts, verify, and cert from httpx.Request().
Related
httpx.RequestClient.send()AsyncClient.send()httpx.request()Response