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 | 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#

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. Una str viene codificata in UTF-8 prima dell’invio. 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 — Dict di header aggiuntivi della richiesta. Il dict viene copiato, quindi quello del chiamante non viene mai modificato (e un header Authorization aggiunto per auth non si propaga alle richieste successive che lo riutilizzano).

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

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

  • timeout — Timeout del socket in secondi, applicato una volta stabilita la connessione. Il valore predefinito è 5.0; passa None per bloccare indefinitamente. Allo scadere viene sollevata una OSError.

Le risposte inviate con Transfer-Encoding: chunked vengono decodificate in modo trasparente, quindi requests.Response.content contiene sempre il corpo ricomposto (de-chunked). Gli header di risposta vengono confrontati senza distinzione tra maiuscole e minuscole. I redirect non vengono seguiti: una risposta 3xx con un header Location solleva NotImplementedError.

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.

  • timeout (kwarg) – timeout del socket in secondi (predefinito 5.0).

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.

  • timeout (kwarg) – timeout del socket in secondi (predefinito 5.0). Aumentalo per endpoint lenti come le API LLM.

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.