Preflight request construction
Inspect or modify the fully assembled URL and headers before transmission.
Requests · Class
Request
Request is a user-created description of an HTTP request. Prepare it to obtain a PreparedRequest that can be sent to a server.
How it works
Request is the user-facing description of an HTTP operation. It stores the method, target URL, headers, query parameters, body, cookies, authentication, and related options; call prepare() to turn it into a PreparedRequest that can be sent.
Syntax
requests.Request(method: str | None = None, url: str | bytes | None = None, headers: Mapping[str, str] | None = None, files: Mapping | None = None, data: Mapping | Iterable[tuple] | str | bytes | file-like | None = None, params: Mapping | Iterable[tuple] | str | bytes | None = None, auth: tuple | callable | None = None, cookies: Mapping | CookieJar | None = None, hooks: Mapping[str, list[callable]] | None = None, json: Any = None)Parameters
| Name | Type | Description |
|---|---|---|
method | str | None | HTTP method to use. |
url | str | bytes | URL to send the request to. |
headers | Mapping[str, str] | None | Dictionary of HTTP headers to send with the request. |
params | Mapping | Iterable[tuple] | str | bytes | None | Dictionary, list of tuples, or bytes for the query string. |
data | Mapping | Iterable[tuple] | str | bytes | file-like | None | Body to attach to the request. |
json | Any | JSON data to send in the request body. |
cookies | Mapping | CookieJar | None | Cookies to include. |
auth | tuple | callable | None | Authentication credentials. |
files | Mapping | None | Files to upload. |
hooks | Mapping[str, list[callable]] | None | Request hooks. |
Returns
A Request instance; after preparation, prepare() returns a PreparedRequest.
Key points
- Instantiate Request when you need an explicit object representing the operation before it is prepared or sent.
- prepare() converts the high-level Request into the wire-ready PreparedRequest.
- The method argument selects the HTTP verb, such as GET, POST, PUT, PATCH, or DELETE.
- Use data for a request body when sending form data, bytes, or a file-like object.
Common mistakes
- Constructing a Request does not send network traffic; prepare it first, or use a session/request API to send it.
- Request is a description object rather than the response returned by the server.
Example: Create and prepare a Request
import requests
request = requests.Request(
method="GET",
url="https://httpbin.org/get",
params={"page": "1"},
headers={"Accept": "application/json"},
)
prepared = request.prepare()
print(prepared.url)Creates a Request description, then prepares it so its final URL and headers can be inspected before sending.
When to use it
Reusable request descriptions
Build reusable request templates with consistent method, payload, and metadata.
Controlled dispatch
Separate request creation from sending through a Session or another transport workflow.
Interview questions
QWhat is the role of requests.Request?
Request represents a user-created HTTP request description. It can be prepared into a PreparedRequest, which is the form sent to the server.
Follow-up: How would you inspect the final URL before transmission? Call prepare() and inspect the resulting PreparedRequest, including its URL.
QWhich information can a Request hold?
The method identifies the HTTP operation, while url identifies the target. Optional fields such as params, headers, data, json, cookies, auth, hooks, and files customize the request.
Follow-up: What happens to query parameters? They are incorporated into the prepared request URL rather than remaining only in the Request object.
QWhen would you use Request instead of requests.get()?
Request is useful when request construction and transmission should be separate. After creating it, prepare() produces a PreparedRequest that can be sent through a session.
Follow-up: Why use a Session for sending? A session can persist configuration and cookies and reuse connections across requests.
Related
PreparedRequestSessionResponseRequestEncodingMixinrequests.request