requests — Client HTTP

Il modulo requests fornisce un’API client HTTP/HTTPS minimale simile alla libreria Python requests. Ogni funzione di richiesta restituisce un oggetto requests.Response.

Esempio:

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())

Classe Response

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

Rappresenta una risposta HTTP. Le istanze vengono restituite da requests.request e dagli helper specifici per metodo.

status_code: int

Codice di stato HTTP intero restituito dal server.

reason: str

Frase di motivo restituita dal server (str decodificata).

encoding: str

Codifica della stringa usata per decodificare requests.Response.headers e requests.Response.content. Il valore predefinito è "utf-8".

headers: str

Header della risposta decodificati con requests.Response.encoding e restituiti come str.

content: str

Corpo della risposta decodificato con requests.Response.encoding e restituito come str.

json() → dict

Analizza requests.Response.content come JSON e restituisce l’oggetto risultante.

Funzioni

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

Invia una richiesta HTTP a url e restituisce un requests.Response.

  • method — Metodo HTTP come str (ad esempio "GET", "POST").

  • url — URL di destinazione. Deve iniziare con http:// o https://.

  • data — Corpo grezzo della richiesta. Se impostato, Content-Length viene aggiunto automaticamente.

  • json — Oggetto serializzato in JSON e inviato come corpo. Imposta Content-Type: application/json.

  • files — Dizionario che associa il nome del campo a una tupla (filename, fileobj). Inviato come multipart/form-data.

  • headers — Dizionario di header aggiuntivi della richiesta.

  • auth — Tupla (username, password) per l’autenticazione HTTP Basic.

  • stream — Accettato per compatibilità con l’API; non utilizzato.

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

Invia una richiesta HTTP HEAD e restituisce un Response.

HEAD è identico a GET tranne che il server risponde solo con la riga di stato e gli header; il corpo è vuoto. Usalo per verificare se una risorsa esiste, ispezionare Content-Length / Content-Type senza scaricare il payload, o sondare un URL prima di effettuare un GET più pesante.

Argomenti:

  • url – URL di destinazione; deve iniziare con http:// o https://.

  • headers (kwarg) – dizionario di header aggiuntivi della richiesta.

  • auth (kwarg) – tupla (username, password) per l’autenticazione HTTP Basic.

data / json / files / stream di request() sono accettati per completezza ma hanno raramente senso per HEAD.

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

Invia una richiesta HTTP GET e restituisce un Response.

GET è il verbo standard per recuperare una rappresentazione della risorsa identificata da url. È sicuro (non causa alcun cambiamento di stato lato server) e idempotente.

Argomenti:

  • url – URL di destinazione; deve iniziare con http:// o https://.

  • headers (kwarg) – dizionario di header aggiuntivi della richiesta (ad esempio Authorization o Accept).

  • auth (kwarg) – tupla (username, password) per l’autenticazione HTTP Basic.

Un corpo di richiesta tramite data / json è consentito dal sottostante request() ma viene ignorato dalla maggior parte dei server.

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

Invia una richiesta HTTP POST e restituisce un Response.

POST invia dati a url, tipicamente creando una nuova risorsa subordinata, attivando l’invio di un modulo o invocando un’azione. Non è né sicuro né idempotente: chiamate ripetute possono creare risorse duplicate.

Argomenti:

  • url – URL di destinazione; deve iniziare con http:// o https://.

  • data (kwarg) – corpo grezzo della richiesta (di tipo bytes). Invia automaticamente un header Content-Length.

  • json (kwarg) – oggetto serializzato in JSON e inviato come corpo. Imposta Content-Type: application/json.

  • files (kwarg) – dizionario che associa un nome di campo a (filename, fileobj). Inviato come multipart/form-data.

  • headers (kwarg) – dizionario di header aggiuntivi della richiesta.

  • auth (kwarg) – tupla (username, password) per l’autenticazione HTTP Basic.

Passa al massimo uno tra data / json / files.

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

Invia una richiesta HTTP PUT e restituisce un Response.

PUT sostituisce la risorsa a url con la rappresentazione fornita, creandola se non esiste. È idempotente: ripetere un PUT identico produce lo stesso stato finale.

Argomenti:

  • url – URL di destinazione; deve iniziare con http:// o https://.

  • data (kwarg) – corpo grezzo di sostituzione (di tipo bytes).

  • json (kwarg) – oggetto serializzato in JSON e inviato come corpo di sostituzione. Imposta Content-Type: application/json.

  • headers (kwarg) – dizionario di header aggiuntivi della richiesta.

  • auth (kwarg) – tupla (username, password) per l’autenticazione HTTP Basic.

Passa data oppure json per trasportare la nuova rappresentazione.

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

Invia una richiesta HTTP PATCH e restituisce un Response.

PATCH applica una modifica parziale alla risorsa a url – cambiano solo i campi contenuti nel corpo della richiesta. A differenza di PUT, non è tenuto a essere idempotente (anche se molte API lo rendono tale).

Argomenti:

  • url – URL di destinazione; deve iniziare con http:// o https://.

  • data (kwarg) – corpo grezzo del delta (di tipo bytes). Il formato dipende dal server (ad esempio JSON Patch, JSON Merge Patch).

  • json (kwarg) – oggetto delta serializzato in JSON. Imposta Content-Type: application/json.

  • headers (kwarg) – dizionario di header aggiuntivi della richiesta.

  • auth (kwarg) – tupla (username, password) per l’autenticazione HTTP Basic.

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

Invia una richiesta HTTP DELETE e restituisce un Response.

DELETE richiede la rimozione della risorsa a url. È idempotente: eliminare una risorsa già eliminata non è un errore (il server tipicamente restituisce un 404, ma lo stato finale è lo stesso).

Argomenti:

  • url – URL di destinazione; deve iniziare con http:// o https://.

  • headers (kwarg) – dizionario di header aggiuntivi della richiesta.

  • auth (kwarg) – tupla (username, password) per l’autenticazione HTTP Basic.

Un corpo tramite data / json è consentito dal sottostante request() ma viene usato raramente con DELETE.