httpx & requests

requests é o cliente HTTP síncrono clássico; httpx é seu sucessor moderno com suporte a async, HTTP/2 e padrões mais rigorosos. Ambos pertencem ao kit de ferramentas de todo desenvolvedor Python para APIs, webhooks e chamadas de serviço a serviço.

Receita

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

Quando usar isso:

• Chamando APIs REST/JSON de scripts, workers ou tarefas em segundo plano do FastAPI
• Necessidade de HTTP assíncrono em rotas asyncio (AsyncClient do httpx)
• Upload de arquivos ou streaming de respostas grandes
• Substituindo chamadas urllib ad-hoc por código legível e testável

Exemplo de Trabalho

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

O que isso demonstra:

• base_url evita repetir prefixos de host
• Timeout explícito divide os limites de conexão e leitura
• raise_for_status() transforma 4xx/5xx em exceções
• Pydantic valida payloads JSON na fronteira
• O mesmo padrão funciona síncrono (Client) e assíncrono (AsyncClient)

Mergulho Profundo

Como Funciona

• Pooling de Conexão - Reutilizar um Client mantém as sessões TCP/TLS ativas; httpx.get() isolado cria um novo pool a cada chamada.
• Timeouts - httpx.Timeout aceita limites de conexão, leitura, escrita e pool; valores não definidos usam o padrão (5s no httpx).
• Redirecionamentos - Seguidos por padrão; desabilite com follow_redirects=False para OAuth ou URLs assinadas.
• Streaming - client.stream("GET", url) produz pedaços sem carregar o corpo completo na memória.

Ciclo de Vida do Cliente

Notas Python

# Mapeie erros de transporte para sua camada de domínio
try:
    response = client.post("/orders", json=payload)
    response.raise_for_status()
except httpx.TimeoutException as exc:
    raise ServiceUnavailable("timeout do upstream") from exc
except httpx.HTTPStatusError as exc:
    if exc.response.status_code == 404:
        raise NotFound("pedido não encontrado")
    raise

Armadilhas

• Nenhum timeout definido - Congelamentos infinitos paralisam workers e obscurecem interrupções. Correção: sempre passe timeout=.
• Criar um novo cliente por solicitação - Destrói o pooling e retarda as negociações TLS. Correção: reutilize Client/AsyncClient.
• Confiar em JSON sem validação - Desvios de esquema causam KeyError profundamente na lógica de negócios. Correção: valide com Pydantic na fronteira HTTP.
• Bloquear requests dentro de rotas assíncronas - Bloqueia o loop de eventos sob carga. Correção: use httpx.AsyncClient ou asyncio.to_thread.
• Ignorar redirecionamentos em POST - Algumas APIs retornam 302 para um host diferente. Correção: registre response.history ao depurar fluxos de autenticação.
• Segredos codificados em URLs - Tokens de consulta acabam em logs. Correção: use cabeçalhos (Authorization) e censure em middleware de log.

Alternativas

FAQs

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

Relacionados

• tenacity - retentativas e backoff para upstreams instáveis
• pydantic-settings - configuração tipada para URLs base de API
• FastAPI Basics - rotas assíncronas que chamam APIs externas
• beautifulsoup4 & lxml - análise de HTML obtido via HTTP

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+ e uv 0.6+.