HTTPX Snippets: um guia prático

1 Introdução ao HTTPX

HTTPX é o cliente HTTP moderno para Python. Ele preserva a familiar API de requests, ao mesmo tempo que oferece suporte a HTTP/2, suporte assíncrono e pool de conexões nativamente. Se você conhece requests, já conhece a maior parte do HTTPX — basta adicionar “síncrono ou assíncrono?” à sua lista mental.

Síncrono e assíncrono com o mesmo modelo mental
Protocolos modernos: HTTP/2 quando disponível
Ótimos padrões: pool de conexões, timeouts, retentativas

Clique em “Próximo” para instalar o HTTPX e enviar sua primeira requisição.

2 Instalação

Use um ambiente virtual — depois instale o HTTPX. O extra [http] carrega o transporte padrão (nenhuma dependência adicional necessária).

pip install httpx[http]

Se precisar de HTTP/2, instale também o h2: pip install h2. Para HTTPS no macOS, você pode precisar de certificados: pip install certifi e defina SSL_CERT_FILE ou REQUESTS_CA_BUNDLE.

3 Um GET Simples

Aqui está um GET síncrono mínimo. Ele imprime o status e um pequeno trecho.

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

O cliente é usado como um gerenciador de contexto para que as conexões sejam liberadas de forma limpa. Isso por si só evita um número surpreendente de erros de “muitos arquivos abertos”.

4 Cabeçalhos, Parâmetros e Timeouts

Passe cabeçalhos e parâmetros de consulta como dicionários simples. Sempre defina 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"))

Use um base_url para reduzir duplicação e r.raise_for_status() para transformar erros HTTP em exceções em vez de falhas silenciosas.

5 POST com JSON

POSTs JSON são de uma linha. O cliente serializa e define o Content-Type correto.

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 Tratamento de Erros

Use exceções específicas sempre que possível; caso contrário, recorra à classe 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("Não foi possível conectar (rede inativa, DNS, recusado).")
except ReadTimeout:
    print("Servidor demorou muito para responder.")
except RemoteProtocolError:
    print("Conexão interrompida no meio do voo.")
except httpx.HTTPStatusError as e:
    print(f"Erro HTTP: {e.response.status_code} {e.response.reason_phrase}")
except httpx.RequestError as e:
    print(f"Requisição falhou: {e}")

7 Requisições Assíncronas (asyncio)

Mude para httpx.AsyncClient quando precisar de concorrência. Agrupe chamadas de I/O com 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 Retentativas e Backoff

Para falhas transitórias, envolva o transporte com uma política de retentativa usando httpx.Limits e 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: a lógica de retentativa reside na camada de transporte. Mantenha-a conservadora — retentativas podem amplificar interrupções.

9 Timeouts Avançados

Divida timeouts de conexão e de leitura para um controle mais preciso. Você também pode desabilitar o timeout de leitura (None) para respostas 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")  # stream lines
    for line in r.iter_lines():
        print(line)

10 Enviando Arquivos (Multipart)

Envie arquivos com files= e campos de formulário regulares com 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 Usando HTTPX no FastAPI

Crie um cliente único e reutilizável na inicialização do aplicativo; feche-o no desligamento.

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

Em produção, monte Limits e uma política de retentativa no transporte. Cacheie respostas comuns se o upstream for muito ativo.