requests — Cliente HTTP

El módulo requests proporciona una API mínima de cliente HTTP/HTTPS similar a la biblioteca Python requests. Cada función de petición devuelve un objeto requests.Response.

Ejemplo:

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

Clase Response

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

Representa una respuesta HTTP. Las instancias son devueltas por requests.request y por los ayudantes por método.

status_code: int

Código de estado HTTP entero devuelto por el servidor.

reason: str

Frase de motivo devuelta por el servidor (str decodificada).

encoding: str

Codificación de cadena usada para decodificar requests.Response.headers y requests.Response.content. El valor predeterminado es "utf-8".

headers: str

Cabeceras de respuesta decodificadas con requests.Response.encoding y devueltas como str.

content: str

Cuerpo de la respuesta decodificado con requests.Response.encoding y devuelto como str.

json() → dict

Analiza requests.Response.content como JSON y devuelve el objeto resultante.

Funciones

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

Envía una petición HTTP a url y devuelve un requests.Response.

  • method — Método HTTP como str (por ejemplo, "GET", "POST").

  • url — URL de destino. Debe empezar por http:// o https://.

  • data — Cuerpo de petición en bruto. Si se establece, Content-Length se añade automáticamente.

  • json — Objeto serializado a JSON y enviado como cuerpo. Establece Content-Type: application/json.

  • files — Diccionario que asigna un nombre de campo a una tupla (filename, fileobj). Se envía como multipart/form-data.

  • headers — Diccionario de cabeceras de petición adicionales.

  • auth — Tupla (username, password) para autenticación HTTP básica.

  • stream — Aceptado por compatibilidad de API; no se usa.

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

Envía una petición HTTP HEAD y devuelve un Response.

HEAD es idéntico a GET salvo que el servidor responde únicamente con la línea de estado y las cabeceras; el cuerpo está vacío. Úselo para comprobar si un recurso existe, inspeccionar Content-Length / Content-Type sin descargar la carga útil, o sondear una URL antes de emitir un GET más pesado.

Argumentos:

  • url – URL de destino; debe empezar por http:// o https://.

  • headers (kwarg) – diccionario de cabeceras de petición adicionales.

  • auth (kwarg) – tupla (username, password) para autenticación HTTP básica.

data / json / files / stream de request() se aceptan por completitud, pero rara vez tienen sentido para HEAD.

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

Envía una petición HTTP GET y devuelve un Response.

GET es el verbo estándar para recuperar una representación del recurso identificado por url. Es seguro (no provoca cambios de estado en el servidor) e idempotente.

Argumentos:

  • url – URL de destino; debe empezar por http:// o https://.

  • headers (kwarg) – diccionario de cabeceras de petición adicionales (por ejemplo, Authorization o Accept).

  • auth (kwarg) – tupla (username, password) para autenticación HTTP básica.

El request() subyacente permite un cuerpo de petición mediante data / json, pero la mayoría de los servidores lo ignoran.

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

Envía una petición HTTP POST y devuelve un Response.

POST envía datos a url, normalmente creando un nuevo recurso subordinado, desencadenando el envío de un formulario o invocando una acción. No es ni seguro ni idempotente: las llamadas repetidas pueden crear recursos duplicados.

Argumentos:

  • url – URL de destino; debe empezar por http:// o https://.

  • data (kwarg) – cuerpo de petición en bruto (similar a bytes). Envía una cabecera Content-Length automáticamente.

  • json (kwarg) – objeto serializado a JSON y enviado como cuerpo. Establece Content-Type: application/json.

  • files (kwarg) – diccionario que asigna un nombre de campo a (filename, fileobj). Se envía como multipart/form-data.

  • headers (kwarg) – diccionario de cabeceras de petición adicionales.

  • auth (kwarg) – tupla (username, password) para autenticación HTTP básica.

Pase como máximo uno de data / json / files.

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

Envía una petición HTTP PUT y devuelve un Response.

PUT reemplaza el recurso en url con la representación suministrada, creándolo si no existe. Es idempotente: repetir un PUT idéntico produce el mismo estado final.

Argumentos:

  • url – URL de destino; debe empezar por http:// o https://.

  • data (kwarg) – cuerpo de reemplazo en bruto (similar a bytes).

  • json (kwarg) – objeto serializado a JSON y enviado como cuerpo de reemplazo. Establece Content-Type: application/json.

  • headers (kwarg) – diccionario de cabeceras de petición adicionales.

  • auth (kwarg) – tupla (username, password) para autenticación HTTP básica.

Pase data o json para transportar la nueva representación.

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

Envía una petición HTTP PATCH y devuelve un Response.

PATCH aplica una modificación parcial al recurso en url – solo cambian los campos contenidos en el cuerpo de la petición. A diferencia de PUT, no se requiere que sea idempotente (aunque muchas API lo hacen así).

Argumentos:

  • url – URL de destino; debe empezar por http:// o https://.

  • data (kwarg) – cuerpo delta en bruto (similar a bytes). El formato depende del servidor (por ejemplo, JSON Patch, JSON Merge Patch).

  • json (kwarg) – objeto delta serializado a JSON. Establece Content-Type: application/json.

  • headers (kwarg) – diccionario de cabeceras de petición adicionales.

  • auth (kwarg) – tupla (username, password) para autenticación HTTP básica.

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

Envía una petición HTTP DELETE y devuelve un Response.

DELETE solicita la eliminación del recurso en url. Es idempotente: eliminar un recurso ya eliminado no es un error (el servidor normalmente devuelve un 404, pero el estado final es el mismo).

Argumentos:

  • url – URL de destino; debe empezar por http:// o https://.

  • headers (kwarg) – diccionario de cabeceras de petición adicionales.

  • auth (kwarg) – tupla (username, password) para autenticación HTTP básica.

El request() subyacente permite un cuerpo mediante data / json, pero rara vez se usa con DELETE.