requests — HTTP client#

The requests module provides a minimal HTTP/HTTPS client API similar to the Python requests library. Each request function returns a requests.Response object.

Example:

import requests

# GET a JSON resource.
r = requests.get("https://httpbin.org/get")
print(r.status_code, r.reason)
print(r.json())

# POST JSON.
r = requests.post(
    "https://httpbin.org/post",
    json={"id": 1, "value": 42},
    headers={"X-Source": "openmv"},
)
print(r.json())

Response class#

class requests.Response(code: int, reason: str, headers: bytes = None, content: bytes = None)#

Represents an HTTP response. Instances are returned by requests.request and the per-method helpers.

status_code: int#

Integer HTTP status code returned by the server.

reason: str#

Reason phrase returned by the server (decoded str).

encoding: str#

String encoding used to decode requests.Response.headers and requests.Response.content. Defaults to "utf-8".

headers: str#

Response headers decoded with requests.Response.encoding and returned as a str.

content: str#

Response body decoded with requests.Response.encoding and returned as a str.

json() → dict#

Parse requests.Response.content as JSON and return the resulting object.

Functions#

requests.request(method: str, url: str, data: bytes | str | None = None, json: Any | None = None, files: dict | None = None, headers: dict | None = None, auth: tuple | None = None, stream: Any | None = None, timeout: float | None = 5.0) → Response#

Send an HTTP request to url and return a requests.Response.

  • method — HTTP method as a str (e.g. "GET", "POST").

  • url — Target URL. Must start with http:// or https://.

  • data — Raw request body. A str is UTF-8 encoded before sending. If set, Content-Length is added automatically.

  • json — Object serialized to JSON and sent as the body. Sets Content-Type: application/json.

  • files — Dict mapping field name to a (filename, fileobj) tuple. Sent as multipart/form-data.

  • headers — Dict of additional request headers. The dict is copied, so the caller’s dict is never modified (and an Authorization header added for auth does not leak into later requests that reuse it).

  • auth — (username, password) tuple for HTTP Basic authentication.

  • stream — Accepted for API compatibility; not used.

  • timeout — Socket timeout in seconds, applied once the connection is established. Defaults to 5.0; pass None to block indefinitely. On expiry an OSError is raised.

Responses sent with Transfer-Encoding: chunked are decoded transparently, so requests.Response.content always holds the de-chunked body. Response headers are matched case-insensitively. Redirects are not followed: a 3xx response with a Location header raises NotImplementedError.

requests.head(url: str, **kw: Any) → Response#

Send an HTTP HEAD request and return a Response.

HEAD is identical to GET except the server replies with only the status line and headers; the body is empty. Use it to check whether a resource exists, inspect Content-Length / Content-Type without downloading the payload, or probe a URL before issuing a heavier GET.

Arguments:

  • url – target URL; must start with http:// or https://.

  • headers (kwarg) – dict of additional request headers.

  • auth (kwarg) – (username, password) tuple for HTTP Basic authentication.

data / json / files / stream from request() are accepted for completeness but rarely make sense for HEAD.

requests.get(url: str, **kw: Any) → Response#

Send an HTTP GET request and return a Response.

GET is the standard verb for retrieving a representation of the resource identified by url. It is safe (causes no server-side state change) and idempotent.

Arguments:

  • url – target URL; must start with http:// or https://.

  • headers (kwarg) – dict of additional request headers (for example Authorization or Accept).

  • auth (kwarg) – (username, password) tuple for HTTP Basic authentication.

  • timeout (kwarg) – socket timeout in seconds (default 5.0).

A request body via data / json is permitted by the underlying request() but ignored by most servers.

requests.post(url: str, **kw: Any) → Response#

Send an HTTP POST request and return a Response.

POST submits data to url, typically creating a new subordinate resource, triggering a form submission, or invoking an action. It is neither safe nor idempotent: repeated calls may create duplicate resources.

Arguments:

  • url – target URL; must start with http:// or https://.

  • data (kwarg) – raw request body (bytes-like). Sends a Content-Length header automatically.

  • json (kwarg) – object serialised to JSON and sent as the body. Sets Content-Type: application/json.

  • files (kwarg) – dict mapping a field name to (filename, fileobj). Sent as multipart/form-data.

  • headers (kwarg) – dict of additional request headers.

  • auth (kwarg) – (username, password) tuple for HTTP Basic authentication.

  • timeout (kwarg) – socket timeout in seconds (default 5.0). Raise it for slow endpoints such as LLM APIs.

Pass at most one of data / json / files.

requests.put(url: str, **kw: Any) → Response#

Send an HTTP PUT request and return a Response.

PUT replaces the resource at url with the supplied representation, creating it if it does not exist. It is idempotent: repeating an identical PUT yields the same final state.

Arguments:

  • url – target URL; must start with http:// or https://.

  • data (kwarg) – raw replacement body (bytes-like).

  • json (kwarg) – object serialised to JSON and sent as the replacement body. Sets Content-Type: application/json.

  • headers (kwarg) – dict of additional request headers.

  • auth (kwarg) – (username, password) tuple for HTTP Basic authentication.

Pass either data or json to carry the new representation.

requests.patch(url: str, **kw: Any) → Response#

Send an HTTP PATCH request and return a Response.

PATCH applies a partial modification to the resource at url – only the fields contained in the request body change. Unlike PUT, it is not required to be idempotent (though many APIs make it so).

Arguments:

  • url – target URL; must start with http:// or https://.

  • data (kwarg) – raw delta body (bytes-like). Format depends on the server (e.g. JSON Patch, JSON Merge Patch).

  • json (kwarg) – delta object serialised to JSON. Sets Content-Type: application/json.

  • headers (kwarg) – dict of additional request headers.

  • auth (kwarg) – (username, password) tuple for HTTP Basic authentication.

requests.delete(url: str, **kw: Any) → Response#

Send an HTTP DELETE request and return a Response.

DELETE requests removal of the resource at url. It is idempotent: deleting an already-deleted resource is not an error (the server typically returns a 404, but the end state is the same).

Arguments:

  • url – target URL; must start with http:// or https://.

  • headers (kwarg) – dict of additional request headers.

  • auth (kwarg) – (username, password) tuple for HTTP Basic authentication.

A body via data / json is allowed by the underlying request() but rarely used with DELETE.