HTTPX Snippets: una guía práctica

1 Introducción a HTTPX

HTTPX es el cliente HTTP moderno para Python. Conserva la familiar API de requests, al tiempo que te ofrece HTTP/2, soporte asíncrono y pooling de conexiones de forma nativa. Si conoces requests, ya sabes la mayor parte de HTTPX—solo tienes que añadir “¿síncrono o asíncrono?” a tu lista mental.

Síncrono y asíncrono con el mismo modelo mental
Protocolos modernos: HTTP/2 cuando esté disponible
Excelentes valores por defecto: pooling de conexiones, timeouts, reintentos

Haz clic en “Siguiente” para instalar HTTPX y enviar tu primera petición.

2 Instalación

Utiliza un entorno virtual—luego instala HTTPX. La extensión [http] incluye el transporte estándar (no se requieren dependencias adicionales).

pip install httpx[http]

Si necesitas HTTP/2, también instala h2: pip install h2. Para HTTPS en macOS, puede que necesites certificados: pip install certifi y configura SSL_CERT_FILE o REQUESTS_CA_BUNDLE.

3 Un GET Simple

Aquí tienes un GET síncrono mínimo. Imprime el estado y un breve extracto.

import httpx

with httpx.Client() as client:
    r = client.get("https://httpbin.org/get")
    print("status:", r.status_code)
    print("content[:120]:", r.text[:120])

El cliente se usa como gestor de contexto para que las conexiones se liberen limpiamente. Eso por sí solo previene un número sorprendente de errores de “demasiados archivos abiertos”.

4 Cabeceras, Parámetros y Timeouts

Pasa cabeceras y parámetros de consulta como diccionarios normales. Siempre establece timeouts explícitos.

import httpx

with httpx.Client(
    base_url="https://httpbin.org",
    headers={"User-Agent": "httpx-snippets/1.0"},
    params={"page": "1", "per_page": "5"},
    timeout=5.0,
) as client:
    r = client.get("/get")
    r.raise_for_status()
    data = r.json()
    print(data.get("args"))

Usa una base_url para reducir la duplicación y r.raise_for_status() para convertir errores HTTP en excepciones en lugar de fallos silenciosos.

5 POST con JSON

Los POST con JSON son una línea. El cliente serializa y establece el Content-Type correcto.

import httpx

payload = {"name": "Ada", "skills": ["math", "coding"]}

with httpx.Client(base_url="https://httpbin.org") as client:
    r = client.post("/post", json=payload)
    r.raise_for_status()
    print(r.json()["json"])

6 Manejo de Errores

Utiliza excepciones específicas cuando sea posible; de lo contrario, recurre a la clase base.

import httpx
from httpx import ConnectTimeout, ReadTimeout, RemoteProtocolError

try:
    with httpx.Client(timeout=1.0) as client:
        r = client.get("https://httpbin.org/delay/2")
        r.raise_for_status()
except ConnectTimeout:
    print("No se pudo conectar (red caída, DNS, rechazado).")
except ReadTimeout:
    print("El servidor tardó demasiado en responder.")
except RemoteProtocolError:
    print("Conexión perdida a mitad de camino.")
except httpx.HTTPStatusError as e:
    print(f"Error HTTP: {e.response.status_code} {e.response.reason_phrase}")
except httpx.RequestError as e:
    print(f"La petición falló: {e}")

7 Peticiones Asíncronas (asyncio)

Cambia a httpx.AsyncClient cuando necesites concurrencia. Agrupa las llamadas I/O con asyncio.gather.

import asyncio
import httpx

async def fetch(url: str):
    async with httpx.AsyncClient(timeout=5.0) as client:
        r = await client.get(url)
        r.raise_for_status()
        return r.json()

async def main():
    urls = ["https://httpbin.org/get"] * 4
    results = await asyncio.gather(*(fetch(u) for u in urls))
    for i, data in enumerate(results, 1):
        print(i, data.get("origin"))

asyncio.run(main())

8 Reintentos y Backoff

Para fallos transitorios, envuelve el transporte con una política de reintentos usando httpx.Limits y Timeout.

import httpx
from urllib3.util.retry import Retry
from httpx import LegacyHTTPTransport

retry = Retry(
    total=3,
    backoff_factor=0.5,
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET", "POST", "PUT", "DELETE", "HEAD", "OPTIONS"],
)

limits = httpx.Limits(max_keepalive_connections=5, max_connections=10)
timeout = httpx.Timeout(5.0, connect=2.0)

transport = LegacyHTTPTransport(retries=retry)
client = httpx.Client(transport=transport, limits=limits, timeout=timeout)

r = client.get("https://httpbin.org/status/503")
print(r.status_code)

Nota: la lógica de reintentos reside en la capa de transporte. Sé conservador: los reintentos pueden amplificar las interrupciones.

9 Timeouts Avanzados

Divide los timeouts de conexión y de lectura para un control más preciso. También puedes deshabilitar el timeout de lectura (None) para respuestas de streaming.

import httpx

timeout = httpx.Timeout(connect=2.0, read=5.0, write=2.0, pool=1.0)
with httpx.Client(timeout=timeout) as client:
    r = client.get("https://httpbin.org/stream/3")  # líneas de streaming
    for line in r.iter_lines():
        print(line)

10 Subiendo Archivos (Multipart)

Envía archivos con files= y campos de formulario normales con data=.

import httpx

with httpx.Client(base_url="https://httpbin.org") as client:
    with open("README.md", "rb") as f:
        files = {"file": ("README.md", f, "text/markdown")}
        data = {"uploader": "me"}
        r = client.post("/post", files=files, data=data)
        r.raise_for_status()
        print(r.json()["headers"].get("Content-Type"))

11 Uso de HTTPX en FastAPI

Crea un cliente único y reutilizable al inicio de la aplicación; ciérralo al apagarla.

from fastapi import FastAPI
import httpx

app = FastAPI()
client = httpx.Client(base_url="https://httpbin.org", timeout=5.0)

@app.on_event("startup")
async def on_startup():
    await client.__aenter__()

@app.on_event("shutdown")
async def on_shutdown():
    await client.__aexit__(None, None, None)

@app.get("/proxy/get")
async def proxy_get():
    r = await client.get("/get")
    r.raise_for_status()
    return r.json()

En producción, monta Límites y una política de reintentos en el transporte. Cachea respuestas comunes si el upstream es muy activo.