httpx y requests

requests es el cliente HTTP síncrono clásico; httpx es su sucesor moderno con soporte asíncrono, HTTP/2 y valores predeterminados más estrictos. Ambos pertenecen al conjunto de herramientas de todo desarrollador Python para APIs, webhooks y llamadas de servicio a servicio.

Receta

import httpx
 
with httpx.Client(timeout=httpx.Timeout(5.0, connect=2.0)) as client:
    response = client.get("https://httpbin.org/get", params={"q": "python"})
    response.raise_for_status()
    data = response.json()

Cuándo usar esto:

• Llamar a APIs REST/JSON desde scripts, workers o tareas en segundo plano de FastAPI
• Necesidad de HTTP asíncrono en rutas asyncio (httpx.AsyncClient)
• Subir archivos o transmitir respuestas grandes
• Reemplazar llamadas urllib ad hoc con código legible y testeable

Ejemplo de Trabajo

from __future__ import annotations
 
import httpx
from pydantic import BaseModel
 
 
class User(BaseModel):
    id: int
    email: str
 
 
def fetch_user(user_id: int) -> User:
    timeout = httpx.Timeout(10.0, connect=3.0)
    with httpx.Client(base_url="https://api.example.com", timeout=timeout) as client:
        response = client.get(f"/users/{user_id}")
        response.raise_for_status()
        return User.model_validate(response.json())
 
 
async def fetch_user_async(user_id: int) -> User:
    timeout = httpx.Timeout(10.0, connect=3.0)
    async with httpx.AsyncClient(base_url="https://api.example.com", timeout=timeout) as client:
        response = await client.get(f"/users/{user_id}")
        response.raise_for_status()
        return User.model_validate(response.json())
 
 
if __name__ == "__main__":
    print(fetch_user(1))

Lo que esto demuestra:

• base_url evita repetir prefijos de host
• Timeout explícito divide los límites de conexión y lectura
• raise_for_status() convierte 4xx/5xx en excepciones
• Pydantic valida las cargas útiles JSON en el límite
• El mismo patrón funciona de forma síncrona (Client) y asíncrona (AsyncClient)

Inmersión Profunda

Cómo Funciona

• Agrupación de conexiones - Reutilizar un Client mantiene las sesiones TCP/TLS activas; httpx.get() de un solo uso crea un nuevo grupo en cada llamada.
• Timeouts - httpx.Timeout acepta límites de conexión, lectura, escritura y agrupación; los valores no establecidos recurren al valor predeterminado (5s en httpx).
• Redirecciones - Se siguen por defecto; desactiva con follow_redirects=False para OAuth o URLs firmadas.
• Streaming - client.stream("GET", url) produce fragmentos sin cargar el cuerpo completo en memoria.

Ciclo de Vida del Cliente

Notas de Python

# Mapea errores de transporte a tu capa de dominio
try:
    response = client.post("/orders", json=payload)
    response.raise_for_status()
except httpx.TimeoutException as exc:
    raise ServiceUnavailable("upstream timeout") from exc
except httpx.HTTPStatusError as exc:
    if exc.response.status_code == 404:
        raise NotFound("order missing")
    raise

Trampas Comunes

• Sin timeout establecido - Las esperas infinitas bloquean los workers y ocultan las interrupciones. Solución: pasa siempre timeout=.
• Crear un nuevo cliente por solicitud - Destruye la agrupación y ralentiza los apretones de manos TLS. Solución: reutiliza Client/AsyncClient.
• Confiar en JSON sin validación - La deriva del esquema causa KeyError en la lógica de negocio. Solución: valida con Pydantic en el límite HTTP.
• Bloquear requests dentro de rutas asíncronas - Bloquea el bucle de eventos bajo carga. Solución: usa httpx.AsyncClient o asyncio.to_thread.
• Ignorar redirecciones en POST - Algunas APIs devuelven 302 a un host diferente. Solución: registra response.history al depurar flujos de autenticación.
• Secretos codificados en URLs - Los tokens de consulta terminan en los registros. Solución: usa encabezados (Authorization) y redáctalos en el middleware de registro.

Alternativas

Preguntas Frecuentes

with open("report.pdf", "rb") as f:
    client.post("/upload", files={"file": ("report.pdf", f, "application/pdf")})

Relacionado

• tenacity - reintentos y backoff para upstreams inestables
• pydantic-settings - configuración tipada para URLs base de API
• Conceptos básicos de FastAPI - rutas asíncronas que llaman a APIs externas
• beautifulsoup4 & lxml - análisis de HTML obtenido por HTTP

Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.