HTTPX Snippets : un guide pratique

1 Introduction à HTTPX

HTTPX est le client HTTP moderne pour Python. Il conserve l'API familière de `requests` tout en offrant le support HTTP/2, asynchrone et le pooling de connexions dès le départ. Si vous connaissez `requests`, vous connaissez déjà la majeure partie de HTTPX — ajoutez simplement "synchrone ou asynchrone ?" à votre liste de contrôle mentale.

Synchrone et asynchrone avec le même modèle mental
Protocoles modernes : HTTP/2 lorsque disponible
Bons défauts : pooling de connexions, timeouts, tentatives

Cliquez sur "Suivant" pour installer HTTPX et envoyer votre première requête.

2 Installation

Utilisez un environnement virtuel, puis installez HTTPX. L'extra [http] inclut le transport standard (aucune dépendance supplémentaire requise).

pip install httpx[http]

Si vous avez besoin de HTTP/2, installez également h2 : pip install h2. Pour HTTPS sous macOS, vous pourriez avoir besoin de certificats : pip install certifi et définissez SSL_CERT_FILE ou REQUESTS_CA_BUNDLE.

3 Un simple GET

Voici un GET synchrone minimal. Il affiche le statut et un court extrait.

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

Le client est utilisé comme gestionnaire de contexte afin que les connexions soient proprement libérées. Cela seul permet d'éviter un nombre surprenant d'erreurs de type "trop de fichiers ouverts".

4 En-têtes, paramètres et timeouts

Passez les en-têtes et les paramètres de requête sous forme de dictionnaires simples. Définissez toujours des timeouts explicites.

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

Utilisez une `base_url` pour réduire la duplication et `r.raise_for_status()` pour transformer les erreurs HTTP en exceptions plutôt qu'en échecs silencieux.

5 POST avec JSON

Les POSTs JSON sont une ligne. Le client sérialise et définit le bon Content-Type.

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 Gestion des erreurs

Utilisez des exceptions spécifiques lorsque vous le pouvez ; sinon, rabattez-vous sur la classe de 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("Could not connect (network down, DNS, refused).")
except ReadTimeout:
    print("Server took too long to respond.")
except RemoteProtocolError:
    print("Connection dropped mid-flight.")
except httpx.HTTPStatusError as e:
    print(f"HTTP error: {e.response.status_code} {e.response.reason_phrase}")
except httpx.RequestError as e:
    print(f"Request failed: {e}")

7 Requêtes asynchrones (asyncio)

Passez à httpx.AsyncClient lorsque vous avez besoin de concurrence. Groupez les appels d'E/S avec 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 Tentatives et backoff

Pour les échecs transitoires, enveloppez le transport avec une politique de tentative en utilisant httpx.Limits et 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)

Note : la logique de tentative se trouve dans la couche transport. Soyez prudent — les tentatives peuvent amplifier les pannes.

9 Timeouts avancés

Séparez les timeouts de connexion et de lecture pour un contrôle plus précis. Vous pouvez également désactiver le timeout de lecture (None) pour les réponses en flux.

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")  # flux de lignes
    for line in r.iter_lines():
        print(line)

10 Téléchargement de fichiers (Multipart)

Envoyez des fichiers avec files= et des champs de formulaire classiques avec 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 Utilisation de HTTPX dans FastAPI

Créez un client unique et réutilisable au démarrage de l'application ; fermez-le à l'arrêt.

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 production, montez des Limites et une politique de tentative sur le transport. Mettez en cache les réponses courantes si l'amont est bavard.